Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Plugin self-documentation mechanism #49

Open
ctrueden opened this Issue May 1, 2014 · 3 comments

Comments

Projects
None yet
2 participants
@ctrueden
Copy link
Member

commented May 1, 2014

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:

bf-importer

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

This comment has been minimized.

Copy link
Member Author

commented May 1, 2014

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

This comment has been minimized.

Copy link

commented Sep 3, 2015

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

This comment has been minimized.

Copy link

commented Sep 3, 2015

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.