Posted by
Burger Wilhelm on
Apr 15, 2009; 12:55pm
URL: http://imagej.273.s1.nabble.com/an-interface-to-encourage-self-documentation-of-plug-ins-tp3692779p3692788.html
> From: ImageJ Interest Group [mailto:
[hidden email]] On
> Behalf Of Jean-Yves Tinevez
> Hi Wilhelm,
>
> We cannot mix developer documentation and use documentation.
Well, why not?
The line between "developers" and "users" is blurred, since plugins are
not only invoked via the menu but also used from other programs or
scripts. With javadoc, one can place general user information about the
use of the plugin and its parameters etc. upfront. Then, as far as the
implementation goes, javadoc only shows the exposed (public) members of
an API. If a plugin has many of these, they are either relevant for
other developers/users or should not be exposed at all. (I suppose
fields should never be public anyway.)
In this sense, I would actually find it quite attractive to have both
user plus API documentation together in the same place.
> The developer documentation should be generated by javadoc, but it
> documents the metods and fields within the plugin, which is
> generally of 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.
I know. Of course (as Johannes noted) the source file must be available
for this at some point.
--Wilhelm