| Deletions are marked like this. | Additions are marked like this. |
| Line 10: | Line 10: |
| mri_convert --help | mri_convert --help | less |
| Line 20: | Line 20: |
|
Simply the name of your program (ie. mri_convert) |
|
| Line 21: | Line 23: |
|
The command-line calling sequence (ie. mri_convert [options] <in vol> <out vol>) |
|
| Line 22: | Line 26: |
|
Verbose description of the wonders of your program. |
|
| Line 23: | Line 29: |
|
If any, arguments that must be included, without flags, typically an input vol and and output vol. Say 'None' otherwise. |
|
| Line 24: | Line 32: |
|
Flagged args like --input, if thats what you have chosen instead of positional args. 'None' otherwise. |
|
| Line 25: | Line 35: |
|
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}}}. |
|
| Line 26: | Line 38: |
|
The more the merrier. |
|
| Line 27: | Line 41: |
|
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. |
|
| Line 28: | Line 44: |
|
Put this text: {{{Report bugs to <freesurfer@nmr.mgh.harvard.edu>}}} |
|
| Line 29: | Line 47: |
| === Maintainer documentation === |
If there are similar programs, mention them here, ie. mris_convert (is in the See-also section of mri_convert). == Maintainer documentation == |
| Line 32: | Line 52: |
| === Testing === | == Testing == |
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>
See Also
If there are similar programs, mention them here, ie. mris_convert (is in the See-also section of mri_convert).
Maintainer documentation
doxygen text
Testing
script that returns 0 for pass, non-zero for fail