|
Size: 1891
Comment:
|
Size: 2943
Comment:
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 2: | Line 2: |
| Line 7: | Line 6: |
| === End-user documentation === | == End-user documentation == |
| Line 9: | Line 8: |
| Line 10: | Line 10: |
| mri_convert --help | mri_convert --help | less |
| Line 13: | Line 13: |
| Line 16: | Line 17: |
| 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: | |
| Line 17: | Line 19: |
| But first, to keep things simple and 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) |
| Line 19: | Line 22: |
| ===== Name ===== ===== Synopsis ===== ===== Description ===== ===== Positional Arguments ===== ===== Required Flagged Arguments ===== ===== Optional Flagged Arguments ===== ===== Example(s) ===== ===== Reference(s) ===== ===== Reporting ===== ===== See Also ===== |
=== Synopsis === The command-line calling sequence (ie. mri_convert [options] <in vol> <out vol>) |
| Line 30: | Line 25: |
| === Maintainer documentation === | === 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 == |
| Line 33: | 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