|
Size: 1162
Comment: creating doc and test for a new program
|
Size: 1844
Comment:
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 2: | Line 2: |
| Line 7: | Line 6: |
| === 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. [[XmlHelpText|Detailed instructions on how to do this are here.]] |
== 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). [[XmlHelpText|Detailed instructions on how to do this are here.]] To see some nice examples of this help text output, type: |
| Line 10: | Line 9: |
| {{{ mri_convert --help }}} or for a simpler example: |
|
| Line 11: | Line 14: |
| {{{ 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 === |
|
| Line 12: | Line 30: |
| doxygen text | |
| Line 14: | Line 33: |
| script that returns 0 for pass, non-zero for fail |
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