Join GitHub today
GitHub is home to over 31 million developers working together to host and review code, manage projects, and build software together.Sign up
Plugin self-documentation mechanism #49
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.
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.