Currently all advanced help content such as discussion, examples, exit codes etc must be specified directly in annotations on the classes to which they apply. For more complex help this can make editing and reviewing it difficult. Therefore it will be nice if there were variants of the various annotations that instead specified the location of the help content as a path to a resource.
In order to do this we would need to provide support for parsing resources in different ways depending on the intended help format. At a minimum:
for prose content pass a text file treating each instance of two consecutive new lines as a paragraph divider
for tabular content support parsing a file as CSV/TSV
for list content support parsing a file such that each line is a list item
Most of this is fairly trivial or can be done by leveraging existing libraries e.g. Apache Commons CSV
As for processing the annotations the help factories simply need to recognise the new variants and invoke the appropriate parser as necessary
Currently all advanced help content such as discussion, examples, exit codes etc must be specified directly in annotations on the classes to which they apply. For more complex help this can make editing and reviewing it difficult. Therefore it will be nice if there were variants of the various annotations that instead specified the location of the help content as a path to a resource.
In order to do this we would need to provide support for parsing resources in different ways depending on the intended help format. At a minimum:
Most of this is fairly trivial or can be done by leveraging existing libraries e.g. Apache Commons CSV
As for processing the annotations the help factories simply need to recognise the new variants and invoke the appropriate parser as necessary
@ExternalProse
@ExternalExitCodes
@ExternalExamples