| 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 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 ===== ===== Synopsis ===== ===== Description ===== ===== Positional Arguments ===== ===== Required Flagged Arguments ===== ===== Optional Flagged Arguments ===== ===== Example(s) ===== ===== Reference(s) ===== ===== Reporting ===== ===== See Also ===== |
=== Name === === Synopsis === === Description === === Positional Arguments === === Required Flagged Arguments === === Optional Flagged Arguments === === Example(s) === === Reference(s) === === Reporting === === See Also === |
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
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
Synopsis
Description
Positional Arguments
Required Flagged Arguments
Optional Flagged Arguments
Example(s)
Reference(s)
Reporting
See Also
Maintainer documentation
doxygen text
Testing
script that returns 0 for pass, non-zero for fail