Posted by
Adrian Daerr-2 on
Apr 24, 2009; 1:27pm
URL: http://imagej.273.s1.nabble.com/an-interface-to-encourage-self-documentation-of-plug-ins-tp3692779p3692783.html
Thanks for all ideas on ways of shipping documentation with plug-ins
and accessing it. There are clearly trade-offs; let me try to
summarize what has been said on alternatives to a suggested custom
interface:
* Wilhelm Burger suggested using javadoc comments (which allows adding
free-form documentation (e.g. usage info, examples) at the top of
the source-file).
Advantages:
- standard way of documenting java source, with tags etc
- makes sense to have usage+API documentation in same place, because
many ImageJ users are also 'developers' (they invoke plug-ins from
the menu as well as from macros/other plug-ins)
- avoids duplicate comments/documentation (java source comments vs
returning a String through a method);
- existing tools to generate HTML, PDF, from javadoc, implying a
comfortable browsing experience for the user.
Disadvantages:
- needs source (positive side to it: will encourage open source)
- not easy to extract specific info (except maybe @author, @version
tags, but has to be done manually), only all-in-one.
* Paul Johnston proposed a centrally hosted plugin registry and a
package-manager, with submission template requiring documentation
Advantages:
- solves other short-comings of current plug-in-anarchy in the same
move
Disadvantages:
- as Johannes Schindelin underlined (I concur), if there is to much of
a burden to share a plug-in, developers won't bother sharing.
- a lot of work to create the infrastructure (but cf Fiji)
* Grant Harris pointed to the JavaHelp software as an alternative to
javadoc. I only very briefly inspected its documentation, so the
following is maybe false and/or incomplete:
Advantages:
- any HTML-producing editor can be used to write doc.
Disadvantages:
- seems to involve a bit of additional work on plug-in developer to
format help pages for display by this system (minimum: four
meta-data files to edit, from what I understand). As pointed out
above, this might be fatal to the willingness of developers.
- plug-in author has to understand how to build this meta-data. This
is prohibitive in my opinion. Unless the operation is trivial and
well documented, or ImageJ generates the meta-data on the fly.
I like Wilhelm Burger's idea very much, and I just learned that
javadoc can be called from within a Java environment:
http://java.sun.com/j2se/javadoc/faq/index.html#runfromwithinIt would be a pity not to move on now that a lot of ideas came up for
the problem at hand. Here is my suggestion version 2: why not offer
the plug-in author a number of alternatives, and provide some standard
access methods ? A balance where we would avoid being to restrictive
on the author, and yet keep a good chance that ImageJ can present some
documentation:
* let the author adopt any one of the following ways to document a
plugin:
- write java-doc comments, with general usage info and example
up-front;
- implement the PluginDoc interface I suggested earlier, which returns
the doc as tagged fields. A number of these would be mandatory to
guarantee key information;
- write entirely free-form doc in any format (e.g. HTML, PDF, text or
RTF), and (optionnally?) implement an interface (I'd suggest using
PlugInDoc here as well, but can be another 'PlugInExternalDoc'
interface) yielding an URL to
this doc.
* ImageJ (the GUI) offers to show help for a plug-in if either
- the Java source is present, and javadoc can be generated from it;
- the plug-in implements the PluginDoc interface;
- an URL to an external document can be obtained (either through a
specific interface, or by searching for a file
The_Plug_In/index.html, The_Plug_In.pdf, or something of the sort
at
the place where The_Plug_In.class is).
* ImageJ (the API) offers some static methods in the class IJ
(IJ.getPluginAuthor(...) etc) that hide from the user the exact
way in which the info is obtained. That way the PluginDoc interface
stays simple, and other ways of documenting plug-ins may later be
added.
Here is the revised PlugInDoc interface which I would like to propose
to Wayne for inclusion:
http://www.msc.univ-paris-diderot.fr/~daerr/ijstuff/api/PlugInDoc.htmlthe source code is here (for completeness, nothing new here really):
http://www.msc.univ-paris-diderot.fr/~daerr/ijstuff/source/PlugInDoc.javaDo you have more comments on this ? Or suggestions for other keys
which should be mandatory ? Ideas what static IJ.get... methods for
documentation there should be ?