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

Posted by dscho on
URL: http://imagej.273.s1.nabble.com/an-interface-to-encourage-self-documentation-of-plug-ins-tp3692779p3692791.html

Hi,

On Wed, 15 Apr 2009, Burger Wilhelm wrote:

> 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.

As far as I can tell, Javadoc was not meant to generate documentation for
users, but documentation for developers (such as the J2SE API).

Indeed, without the source code, you cannot extract the information from a
plugin using javadoc.

Ciao,
Dscho