BSP Developer's Guide

9
Documentation Guidelines
INCLUDE FILES Section
Every library and driver entry should have a subheading INCLUDE FILES, which
lists any relevant header files, for example:
RETURNS Section
INCLUDE FILES: sysLib.h
The RETURNS section should be the last section before the SEE ALSO section.
■
Include a RETURNS section in all subroutines. If there is no return value (as in
the case of a void) simply enter:
■
■
■
■
■
RETURNS: N/A
Mention only true returns in the RETURNS section—not values copied to a
buffer given as an argument.
Always start a return-value statement with a capital and end it with a period;
and again, do not use abbreviated English. For example:
RETURNS: The address of the top of memory.
Despite the general rule of style, we do not treat return values as complete
sentences; the subject and verb are understood.
Keep return statements in present tense. (Even if the conditions that cause an
ERROR may be thought of as “past” once ERROR is returned.)
In STATUS returns, ERROR must be followed by a qualifying statement.
Always enter a comma after OK, because it must be clear that the qualifier
belongs to the ERROR condition and not the OK. For example:
RETURNS: OK, or ERROR if memory is insufficient.
Do not preface lines of text with extra leading spaces—input lines whose first
characters is a space cause a fill break. In the past, some authors applied this
technique in RETURNS sections to force line breaks for separate elements of a
return—we do not follow this convention. For example:
CORRECT:
* RETURNS: OK, or ERROR if the tick rate is invalid or the timer
* cannot be set.
9
185