Deletions are marked like this. | Additions are marked like this. |
Line 8: | Line 8: |
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.]] |
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: {{{ mri_convert --help }}} or for a simpler example: {{{ mris_inflate --help }}} |
Line 10: | Line 17: |
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 ===== |
|
Line 12: | Line 31: |
doxygen text | |
Line 14: | Line 34: |
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 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
Maintainer documentation
doxygen text
Testing
script that returns 0 for pass, non-zero for fail