Guidance on new program documentation and test

For newly created programs, some documentation and test work items should be created, to aid the end-user and future program maintainers. In creating these docs and tests, it is best to take off your 'developer' hat, and put on your 'end-user' hat, and then your 'maintainer' hat, to gain the view point of someone who has never seen or worked with your program. Your program is new to the end-user or maintainer, and nothing should be assumed about what they know about how it works.

There are three main work items to create: end-user documentation, maintainer documentation, and test code.

End-user documentation

The primary (and typically only) end-user documentation to create is text information like what you see in a unix 'man' page. In freesurfer, as of Feb 2011, the code in the dev tree and v5.1 branch supports putting 'man page'-like information in an xml file, which is then embedded into the .c/.c++/csh program and printed for you in a nice format (also supports automatic creation of a wiki page and pdf doc, TBD). Detailed instructions on how to do this are here. To see some nice examples of this help text output, type:

mri_convert --help | less

or for a simpler example:

mris_inflate --help

But first, to keep things simple, ignoring those instructions and XML for the moment, using your favorite text editor, create a text file containing the follow sections:

Name

Simply the name of your program (ie. mri_convert)

Synopsis

The command-line calling sequence (ie. mri_convert [options] <in vol> <out vol>)

Description

Verbose description of the wonders of your program.

Positional Arguments

If any, arguments that must be included, without flags, typically an input vol and and output vol. Say 'None' otherwise.

Required Flagged Arguments

Flagged args like --input, if thats what you have chosen instead of positional args. 'None' otherwise.

Optional Flagged Arguments

Flagged args, but optional. Note that the XML format allow including additional help text to be associated with an arg. For example, see the <intro>, <argument> and <explanation> tags of the 'Applying Transforms' section of mri_convert.help.xml.

Example(s)

The more the merrier.

Reference(s)

If you have a paper associated with this program, include a reference here. While not necessarily useful for command-line help usage, obviously having a larger context of your program is a big help.

Reporting

Put this text: Report bugs to <freesurfer@nmr.mgh.harvard.edu>

Maintainer documentation

doxygen text

Testing

script that returns 0 for pass, non-zero for fail