[ImageJ-devel] Auto-Documentation of Processing Chain: Extension of @Parameter Annotation

[Oliver Gress]

Hi all,

we have developed a way for automatic documentation of the processing
chain of an image or other results in ImageJ. 
For improved integration with IJ, we would like to discuss a
modification/extension of the @Parameter annotation in IJ-Dev.

The basic concept is to consider each processing step as an "operator",
that takes some input and computes results, which might become input to
another operator. Such an operator may be an ImageJ plugin or any java
class that satisfies the specification.

The specific interface of such an operator is described by inputs,
parameters, supplementals and outputs. 
Inputs and outputs are used to trace the processing chain, from which a
"history" graph is created.
Parameters are inputs that are not traced but recorded. Supplementals
are not recorded at all and are intended for parameters that have no
effect on the results (e.g. a verbose flag).

We employ java annotations to determine the above interpretation of the
fields of a class and thus the interface of an operator.
At the moment, we use our own annotation class, because @Parameter from
IJ-Dev does not allow the detailed categorization of arguments that
would be required by our concept. It only allows to specify if an
argument is output or not. 
I know that @Parameter is intended to describe the parameters of a
plugin, e.g. to create a parameter dialog automatically. 
I'd like to ask if the idea of @Parameter could be extended to a more
general point of view:

Would it be possible to extend or modify the @Parameter annotation to
categorize a field as input, output, parameter or supplemental?
Our annotation also takes an "explanation" string to describe the
parameter in human-readable form, but it is not essential for the
automatic documentation.

We would really like to merge these annotations, because the processing
chain documentation could be easily employed by IJ plugins that use the
@Parameter annotation and no additional annotation would be necessary.

Another question: Is there any interest in an automatic documentation of
the processing chain?


I have uploaded an excerpt of our manual for further reading on the
operator and history concept:
http://users.informatik.uni-halle.de/~gress/mitobo_manual_excerpt.pdf
The manual is rewritten at the moment, therefore only an excerpt. If you
find a link to our website, please don't refer to the resources that can
be found there because they are outdated. There will be a new version
soon (depending on the annotation issue).

Our annotation can be found here:
http://users.informatik.uni-halle.de/~gress/MTBArgumentAnnotation.java


Best regards
Oliver