Re: an interface to encourage self-documentation of plug-ins

Posted by Michael Schmid on Apr 24, 2009; 4:38pm
URL: http://imagej.273.s1.nabble.com/an-interface-to-encourage-self-documentation-of-plug-ins-tp3692779p3692784.html

Hi Adrian,

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.
Clickable URLs would be nice, I agree; being able to copy URLs from  
the showAbout windows would be sufficient. The downside: The URL can  
easily change if the author's institution rearranges the web site or  
the author leaves the institution...

A significant progress would be PDFs/HTMLs+images embedded in a .jar,  
but I fear that only few plugin authors will do that. Also, I am not  
sure whether large .jar files would increase the ImageJ startup time.

A repository for plugins is a different thing - this would be really  
nice!
Then, it would make more sense to have a clickable URL, to have a  
revision date that so one could check for updates, etc.

Just my 3 cents.

Michael
________________________________________________________________

On 24 Apr 2009, at 15:27, Adrian Daerr wrote:

> 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#runfromwithin
>
> It 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.html
>
> the source code is here (for completeness, nothing new here really):
> http://www.msc.univ-paris-diderot.fr/~daerr/ijstuff/source/ 
> PlugInDoc.java
>
>
> Do 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 ?