Plugin self-documentation mechanism

[ctrueden]

To complement an improved plugins infrastructure, it would be nice to have a way for plugin authors to document what their plugin does from an end-user perspective, including the meaning of various parameters.

The idea would be to use Java annotations, Javadoc or something similar, possibly embedded in the source code itself, or possibly in a standard format in some external text file, to document the plugin.

We have attempted this sort of documentation informally with the Bio-Formats Importer plugin:

But it would be better to have an official, more structured solution, encouraging plugin authors to document plugin parameters and features by making it very easy to do so.

Migrated-From: http://trac.imagej.net/ticket/32

[ctrueden]

For description of parameters, I really like Javadoc on the command fields. It is already HTML; the only hard part is that the javadoc is compiled out of the class file...

[adaerr]

Just stumbled across an annotation preprocessor that packs a multiline java comment into an annotated String variable [1]. This might be a way to transform HTML documentation into a plugin parameter.

[1] https://github.com/benelog/multiline

[adaerr]

That said, it would be nice if the infrastructure were more flexible with respect to the documentation format, and allow for external resources (such as PDF files, text/markdown files, or images included in the jar, or accessible via some URI). Think e.g. including a (p)reprint of a publication associated with the plugin. HTML is a bit cumbersume to write, especially regarding maths, and is merely adequate for short explanations as to the meaning of parameters.