79.adoc

Documentation of UIMA components

Concreteness: concrete
Strength: mandatory
Category: WG1,WG4
Status: draft

See also

• [REQ-12]

• [REQ-21]

The documentation of UIMA components should be maintained as JavaDoc in the component source code. The uimaFIT Maven plugin goal enhance picks the documentation of components and parameters up from there and embeds it into the compiled class. The goal generate finally transfers the documentation into the automatically generated UIMA resource specifiers.

The description properties of the uimaFIT @ConfigurationParameter and of the @ResourceMetaData annotations should not be used.

Component documentation should be provided as JavaDoc on the component class itself.

Documentation and parameter constant for UIMA component parameters

/**
 * Part-of-Speech annotator using OpenNLP.
 */
public class OpenNlpPosTagger
	extends JCasAnnotator_ImplBase
{

Parameter documentation should be placed before a constant declaration which defines the parameters name as shown in the example below. This ensures that IDEs show the parameters and associated documentation when auto-completion is invoked on a UIMA component. It also allows the uimaFIT Maven plugin goal enhance to pick up the documentation and to automatically transfer it into the description property.

Documentation and parameter constant for UIMA component parameters

/**
 * Use this language instead of the document language to resolve the model.
 */
public static final String PARAM_LANGUAGE = "language";
@ConfigurationParameter(name = PARAM_LANGUAGE, mandatory = false)
protected String language;

Table 1. Compliance assessment

Product	Version	Compliant	Justification	Status
ARGO	0.5	Partial	Documentation is manually maintained within the UIMA resource specifiers.	Draft
DKPro Core	1.8.0	Full	Documentation is maintained as JavaDoc and transferred into UIMA resource specifiers using the uimaFIT Maven plugin.	Draft
ILSP	1.2.1	Partial	Partial documentation of component source code is maintained and generated as JavaDoc.	Draft