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

Posted by Jean-Yves Tinevez-4 on Apr 15, 2009; 11:49am
URL: http://imagej.273.s1.nabble.com/an-interface-to-encourage-self-documentation-of-plug-ins-tp3692779p3692790.html

On Apr 15, 2009, at 1:23 PM, Burger Wilhelm wrote:

> Hello Adrian,
>
> I fully agree that the lack of documentation is a notorious problem.
> However, I also agree with Johannes that - unless tags are  
> standardized
> and enforced - the gain will be small. Also, for typing documentation
> texts I would certainly prefer a more flexible style than having to
> concatenate individual string elements.
>
> But why invent something new? Javadoc is designed for exactly that and
> is a well-known and standardized mechanism, provides HTML or custom
> formatting, element highlighting etc. I guess it should be possible to
> extract the documentation from a plugin's source file and display it  
> on
> the fly (and cache for later use). The plugin interface need not  
> change
> at all and plugin writers would just have to write standard comments.
>
> --Wilhelm

Hi Wilhelm,

We cannot mix developer documentation and use documentation.
The developer documentation should be generated by javadoc, but it  
documents the metods and fields within the plugin, which is generally  
f little use to the common user.
What Adrian proposes is a way to embed user documentation within  
the .java file, that is how to use the plugin, not how it is written.

cheers
jy