The doctext program searches for C comments of the form /* c ...
c*/, where c is a single character indicating the type of
documentation. The available types are @ for
routines, M for macros, E for enum definitions,
S for struct definitions, and D for
other miscellaneous documentation (such as introductions or descriptions of
programs rather than routines).
In all cases, the structured comment has this form:
/*@ name - short descriptionThe structured comment for a routine must immediately precede the declaration of the routine (either K&R or ANSI-style prototypes). Figure 1 shows the structured comment and the routine being documented.heading 1:
heading 2:
... @*/
/*@ Swap - Swaps two pointersParameters: . ptr1,ptr2 - Pointers to swap @*/ void Swap( ptr1, ptr2 ) void **ptr1, **ptr2; { void *tmp = *ptr1; *ptr1 = *ptr2; *ptr2 = tmp; }
The man (nroff-style) output of this is shown in Figure 2 , and the LaTeX output is shown in Figure Structured Comments .
C Library Functions Swap(3) NAME Swap - Swaps two pointers SYNOPSIS void Swap( ptr1, ptr2 ) void **ptr1, **ptr2; PARAMETERS ptr1,ptr2 - Pointers to swap LOCATION swap.txt Last change: 1/5/2000 1
LaTeX page for the Swap routine
The body of the structured comment follows simple rules. Any line that ends
in a colon (:) generates a section title with the line as the title.
In the example of Swap, the line Parameters: generates a section
in the man page with title Parameters. To end a line in a colon without
generating a section heading, precede it with a backslash:
This is not a new section\:The first column within a structured comment has a special meaning. A period followed by a space indicates that the line begins the description of an argument (ended by another argument or a blank line). This line has a special format. The first space-separated token is taken as the argument. The next character should be a dash (-). After the dash comes the text. The Swap example shows this for the arguments ptr1,ptr2. Other commands are described below in Section Special Formatting .