http://imagej.273.s1.nabble.com/an-interface-to-encourage-self-documentation-of-plug-ins-tp3692779p3692786.html
I think your idea is a good one. I agree with Johannes that the Map
getters/setters. However, I'm not sure this is a problem that's best
solved at the .class level. Rather, having a centrally hosted plugin
plugins would be much better. Then, developers could be required to
Just my two cents. (My apologies if this idea has been discussed
> 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.class>
http://www.msc.univ-paris-diderot.fr/~daerr/ijstuff/source/Get_help_for_PlugIn.class>
> somewhere 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.html>
> For 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.html> show 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
>