
B Documentation Guidelines
B.6 Directives
169
B
Note that these directives should not be used to suppress the publication of an
entire file. The standard way to prevent a file from being processed is to omit it
from the Wind River makefile variable
DOC_FILES.
\INTERNAL [title]
This directive specifies that the following section is internal documentation
and should not be output. An internal section ends with the next heading or
the end of the comment block. If title is specified, it becomes the section title if
apigen is run with -internal; otherwise the section title is “INTERNAL”.
Examples:
\INTERNAL
\INTERNAL IMPLEMENTATION DETAILS
\NOMANUAL
This directive suppresses the entire comment block of a routine or library in
which it occurs. Routines that are declared static or
LOCAL are automatically
\NOMANUAL. If all routines in a library are \NOMANUAL, static, or LOCAL,
the ROUTINES section of the library entry will be generated with the message
“No user-callable routines”.
Use of this directive in a library section is rare. Putting
\NOMANUAL in a
library section does not make its routines internal. The standard way to
prevent an entire file from being processed is to omit it from a makefile
variable.
Example:
/*********************************************************************
*
* stateReset - reset the state machine
*
* This routine returns the internal state to it initial state.
* It should not be called by users.
...
* \NOMANUAL
*/
Although the \NOMANUAL line will be interpreted regardless of where it
appears, the standard practice is to place it at the end of the comment block.
Other Overrides
\TITLE name - shortdescription
The
\TITLE directive replaces a file’s title line (the title in the file’s first
comment block) with whatever follows the directive. Currently it is used
exclusively in BSPs to give the file a more descriptive name than target.ref. The
Comentarios a estos manuales