Structured Comments

PreviousUpNext
Up: The doctext Program Next: C Routines Previous: Getting Started

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 description 

heading 1:

heading 2:

... @*/

The 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.


 
/*@ 
   Swap - Swaps two pointers 

Parameters: . ptr1,ptr2 - Pointers to swap @*/ void Swap( ptr1, ptr2 ) void **ptr1, **ptr2; { void *tmp = *ptr1; *ptr1 = *ptr2; *ptr2 = tmp; }


Figure 1: C code for a Swap routine with doctext-style structured comment

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 

Figure 2: Unix-style man page for the Swap routine

Image file


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 .


PreviousUpNext
Up: The doctext Program Next: C Routines Previous: Getting Started