RAM 6.0 BUX II Series Guía de usuario descargar pdf (Pagina 159)

B Documentation Guidelines

B.3 Sections for Libraries and Subroutines

151

■

Mention only true returns in this section, not values copied to a buffer given as

an argument. (However, do describe the latter in the

DESCRIPTION section.)

■

Despite the general rule of style, we do not treat return values as complete

sentences; the subject and verb are understood. However, always start the

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.

■

Keep return statements in present tense, even if the conditions that cause an

ERROR or any other return value may be thought of as “past” once ERROR is

returned.

CORRECT:

RETURNS: OK, or ERROR if memory is not available.

INCORRECT:

RETURNS: OK, or ERROR if memory was not available.

■

In STATUS returns, ERROR must be followed by a qualifying statement.

Always type 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.

In some cases the return value will be “OK, always” and “ERROR, always.”

■

Do not preface lines of text with extra leading spaces. An input line whose first

character is a space causes 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.

INCORRECT:

* RETURNS: OK, or ERROR

* if the tick rate is invalid or

* the timer cannot be set.

ERRNO or ERRORS Section

For C routines, include a list of all errno values set by this routine (but not values

set by routines that it calls). For Tcl procedures, list all the error messages or error

codes (or both, if necessary) raised in the procedure by the Tcl error command.

1 2 ... 154 155 156 157 158 159 160 161 162 163 164 ... 188 189

Comentarios a estos manuales

Sin comentarios

RAM 6.0 BUX II Series Guía de usuario Pagina 159

Comentarios a estos manuales

Relacionado con productos y manuales para Amplificadores de audio RAM 6.0 BUX II Series