Using the Documentation Generation utilities in Barclay

Placeholder - under construction.

Using the Barclay Documentation Utilities

The Barclay org.broadinstitute.barclay.help package contains utilities for generating html-based documentation for CommandLinePrograms and related classes that are implemented using the Barclay org.broadinstitute.barclay.argparser package. The utilities use the the Apache FreeMarker template engine, and the Barclay org.broadinstitute.barclay.argparser package annotations to produce html output suitable for online help. The documentation process is driven by javadoc, and requires running a javadoc task that uses a specialized Doclet provided by Barclay.

To use the Barclay utilities, you need to provide:

A Java [Doclet] class that is derived from [HelpDoclet] A documentation handler derived from [GenericDocumentationHandler] One or more Freemarker templates. Barclay contains [default versions] of these templates, but most consumers will want to modify them at least minimally to provide application-specific output.

The files in the Barclay help test package contain a simple example that illustrates how to use these utilities. The output generated by the test files can be inspected by looking at the expected test output, included in the repository [here].

Documenting Features - The @DocumentedFeature Annotation

The [DocumentedFeature] annotation is how Barclay knows which features to emit documentation for. The Doclet included in Barclay looks at each class provided via the javadoc process, and processes only classes that are annotated with [DocumentedFeature]. For each such class, a .html file is emitted that contains the javadoc for that class, and automatically generated documentation for each @Argument or @ArgumentCollection annotated command line arguments used in that class, as well as for any [CommandLineDescriptor] controlled plugins for classes that implement.[CommandLineDescriptorPluginProvider].

Customizing the Output

There are several points of extensibility for generating Barclay documentation:

Custom FreeMarker templates. CommandLinePluginDescriptors Custom JavaDoc tags

Custom JavaDoc Tags

A Barclay Doclet can specify a string prefix to be used by Barclay to identify javadoc tags that should be automatically lifted to, and stored in the FreeMarker template, suing the following DocumentationHandler override:

@Override protected String getTagFilterPrefix(){ return "MyTag"; }

Barclay has the ability to embed application-specific javadoc tags in the freemarker template for use in organizing the test output. The custom Doclet can