Posted by
Adrian Daerr-2 on
Apr 14, 2009; 4:28am
URL: http://imagej.273.s1.nabble.com/an-interface-to-encourage-self-documentation-of-plug-ins-tp3692779.html
Dear ImageJ-users,
One of the factors limiting the re-use of the many high quality plug-ins
that exist for ImageJ is in my opinion the lack of documentation (there
are other factors of course). When documentation exists, it is not
always clear where to find it: in the source, on a web-page, ... ?
I think it might be worth trying to define an interface that would allow
and encourage plug-in authors to put any information they might judge
usefull in the view and reach of the users. There has been a weak
tradition of printing some information when the argument to the
PlugIn.run() method is "about", but this was to my knowledge never
really exploited to get information on installed plug-ins, and requires
programming time for anything beyond IJ.log() statements.
In order to launch the discussion, and draw comments and criticism, I
sketched a first attempt at an idea of a documentation interface. I
would very much like to know whether others think this might be a good
idea, whether those writing plug-ins would consider actually using such
a framework, and what could be better.
If you just want to know what I have in mind before reading on, please
consider installing the two class files
http://www.msc.univ-paris-diderot.fr/~daerr/ijstuff/source/PlugInDoc.classhttp://www.msc.univ-paris-diderot.fr/~daerr/ijstuff/source/Get_help_for_PlugIn.classsomewhere in your plugin directory, restart ImageJ and try the
'Get_help_for_PlugIn' plug-in that appeared (if you prefer java files,
just change the extensions in the URLs above from .class to .java). The
current version requires Java >= 1.6 to run (and compile; but it is not
a fundamental problem to back-port this to earlier Java versions).
Or have a look at
http://www.msc.univ-paris-diderot.fr/~daerr/ijstuff/api/PlugInDoc.htmlFor the moment the choice you'll be presented with when running the
plug-in is limited to the plug-in itself, which self-documents when you
click 'ok'. You can have it open the javadoc API, the source code, etc
by checking the boxes in front of the ressources. Is this (i.e. text and
arbitrary URIs) powerful enough ? (obviously the presentation can be
much more fancy, this is just meant to be a proof-of-concept)
Back to the idea, which was to have some lightweight scheme (we can't do
much about the fact that writing documentation is work, but exposing
the information present (in the source, a publication or anywhere on the
internet) to the user should not cost the programmer more than a few
seconds): in addition to the usual PlugIn or PlugInFilter interface, the
plug-in wishing to expose documentation implements a new PlugInDoc
interface, which is defined simply as:
public interface PlugInDoc {
public java.util.Map getDocumentation();
}
and the programmer has to fill in one single method. I hope the examples at
http://www.msc.univ-paris-diderot.fr/~daerr/ijstuff/api/PlugInDoc.htmlshow what I had in mind: writing this method is no harder than any
usage() or about() method delivering only a String, yet quite flexible
and not restrictive.
In this basic version a plug-in is used to inspect other plug-in's
documentation, but there is no obstacle to creating an "about..."
sub-menu containing a replica of the "plugins" menu to directly inspect
the documentation/usage information/update information/... I think there
there is a potential for making plug-ins much easier to use.
Hoping for reactions,
best regards
Adrian