Posted by
Adrian Daerr-2 on
Apr 26, 2009; 10:55am
URL: http://imagej.273.s1.nabble.com/an-interface-to-encourage-self-documentation-of-plug-ins-tp3692779p3692785.html
Hello Michael,
you wrote:
> sorry, I still do not see so much advantage of this over the current
> showAbout() method.
> One could encourage users to write part of the showAbout in a
> standardized way (author, license, revision date), but normally
>there won't be any need to extract these from a program, so any
>format will do.
I am not pretending the advantage is huge. There are a number of
small improvements though, for the prize of three lines of code added
to ImageJ (the interface declaration is really tiny):
- an interface declaration (implements ...) makes it easier to know if
a class exposes documentation (you can check with
'if (plugin instanceof PlugInDoc)' instead of using reflection
methods (see the 10 or so lines of code of the installAbout method
in
http://rsbweb.nih.gov/ij/source/ij/plugin/Installer.java )
This could of course be done keeping the showAbout method, simply by
declaring an interface PlugInAbout { static void showAbout() }. But
while we're at it, maybe the interface could be better, allowing for a
more flexible way of exposing documentation.
- You might want to collect/expose/process the documentation, or just
display it through a common interface, instead of leaving it to every
plug-in to display its own way inside the showAbout() method. What if
you run head-less for example and showAbout tries to open a Dialog ?
- one small piece of information that users might want to have
explicitly is the release date: just as you can check you are running
on a sufficiently recent ImageJ version, it could be nice to be able
to check that the plug-in you intend to call is also sufficiently
recent.
- being able to include URLs in a way that a plug-in can make
clickable is nice, as you say. Have you tried the Get_help_for_plugin
plugin I originally submitted ? -- really easy to do !
Also note that an URL can point to local resources (PDF or HTML+images
or ...), so this is a very nice way of opening up more convenient ways
of writing documentation (than concatenating strings, limited to pure
text).
The interface itself remains very lightweight (one method, lighter as
the showAbout method because displaying the info is left to the
caller, e.g. the ImageJ GUI), so it seems like worthwile improvements
to me.
Johannes Schindelin commented that specific functions (such as
getReleaseDate()) could be more usefull. I concur, but suggest that
such methods be included in the ij.IJ class. The main advantage with
respect to including them in the interface is that new functions can
easily be added later (while you cannot alter an interface once you
have published it). Other small advantages include the fact that the
plug-in writer still has only one method to implement instead of a
whole series, and the possibility of refering to the plug-in by name
(leaving it to the code under the hood of IJ to load the class):
IJ.getPlugInReleaseDate(String plugin).
thanks for the comments,
regards,
Adrian