User`s guide

B Documentation Guidelines

B.3 Sections for Libraries and Subroutines

147

■

Libraries

Describe briefly what this collection of routines does. The hyphen must appear

exactly as indicated (space-hyphen-space)—do not use backslashes or double

hyphens. The general format is:

nameLib.c - the such-and-such library

For example:

sysALib.s - mfr&board system-dependent assembly routines

sysLib.c - mfr&board system-dependent library

Be sure to include the filename extension (.c, .s); but note that the apigen

process strips it off so that it does not appear in the final reference entry.

■

Routines

For the one-line heading/definition, use the imperative mood and convey

action. The general format is:

name - do such and such

For example:

sysMemTop - get the address of the top of memory

Do not include the subroutine parentheses in the heading; the apigen process

adds them in so that they appear in the final reference entry.

ROUTINES Section

This section is generated automatically and lists all subroutines in the library that

are not declared

LOCAL, static, or marked NOMANUAL.

SYNOPSIS Section

C Routines

For a C routine, this section is the declaration. The section heading is generated

automatically and the text is picked up from the declaration in the code, along with

the short comments describing each parameter. In unusual cases where the code

declaration is not appropriate, a SYNOPSIS section can be typed manually in the

routine-header comment block. If apigen sees a manually entered SYNOPSIS, it

replaces the one encountered in the routine code.

NOTE: The routine heading and definition must be limited to one line only.