User`s guide

B Documentation Guidelines
B.3 Sections for Libraries and Subroutines
149
B
comment for each parameter, which serves as a useful overview or memory jogger.
However, these short comments are typically not sufficient for thorough
documentation. The parameter list in the DESCRIPTION section should provide
more information and detail.
Begin the parameter list with the word “Parameters” followed by a colon. Format
the list with the item-list tags \is, \i, and \ie (for more information, see Item Lists
(Definition Lists or Terms Lists), p.163.) Each parameter should be identified with the
\i tag, which should be followed by sentences explaining what it is, what it does,
what sort of values it expects, and how it is used. To keep the input readable,
separate each parameter item with a blank line. For example, consider the routine
unixDiskDevCreate( ) with the following declaration:
BLK_DEV * unixDiskDevCreate
(
char * unixFile, /* name of the UNIX file */
int bytesPerBlk, /* number of bytes per block */
int blksPerTrack, /* number of blcoks per track */
int nBlocks /* number of blocks on this device */
)
The following shows how the parameters would be described in the
DESCRIPTION section:
* Parameters:
* \is
* \i <unixFile>
* The name of the UNIX file for the disk device.
*
* \i <bytesPerBlk>
* The size of each logical block on the disk. If zero,
* the default is 512.
*
* \i <blksPerTrack>
* The number of blocks on each logical track of the disk.
* If zero, the count of blocks per track is set to <nBlocks>;
* that is, the disk is defined as having only a single track.
*
* \i <nBlocks>
* The size of the disk in blocks. If zero, a default size is used;
* the default is calculated as the size of the UNIX disk divided by
* the number of bytes per block.
* \ie
When generated, the above will appear as follows:
Parameters:
unixFile
The name of the UNIX file for the disk device.