5.3 Information Units

XXX Explain terminology, or come up with something more ``lay.''

There are a number of environments used to describe specific features provided by modules. Each environment requires parameters needed to provide basic information about what is being described, and the environment content should be the description. Most of these environments make entries in the general index (if one is being produced for the document); if no index entry is desired, non-indexing variants are available for many of these environments. The environments have names of the form featuredesc, and the non-indexing variants are named featuredescni. The available variants are explicitly included in the list below.

For each of these environments, the first parameter, name, provides the name by which the feature is accessed.

Environments which describe features of objects within a module, such as object methods or data attributes, allow an optional type name parameter. When the feature is an attribute of class instances, type name only needs to be given if the class was not the most recently described class in the module; the name value from the most recent \classdesc is implied. For features of built-in or extension types, the type name value should always be provided. Another special case includes methods and members of general ``protocols,'' such as the formatter and writer protocols described for the formatter module: these may be documented without any specific implementation classes, and will always require the type name parameter to be provided.

\begin{cfuncdesc} {type}{name}{args} \end{cfuncdesc}: Environment used to described a C function. The type should be specified as a typedef name, struct tag, or the name of a primitive type. If it is a pointer type, the trailing asterisk should not be preceded by a space. name should be the name of the function (or function-like pre-processor macro), and args should give the types and names of the parameters. The names need to be given so they may be used in the description.

\begin{ctypedesc} [tag]{name} \end{ctypedesc}: Environment used to described a C type. The name parameter should be the typedef name. If the type is defined as a struct without a typedef, name should have the form struct tag. name will be added to the index unless tag is provided, in which case tag will be used instead. tag should not be used for a typedef name.

\begin{cvardesc} {type}{name} \end{cvardesc}: Description of a global C variable. type should be the typedef name, struct tag, or the name of a primitive type. If variable has a pointer type, the trailing asterisk should not be preceded by a space.

\begin{datadesc} {name} \end{datadesc}: This environment is used to document global data in a module, including both variables and values used as ``defined constants.'' Class and object attributes are not documented using this environment.

\begin{datadescni} {name} \end{datadescni}: Like \datadesc, but without creating any index entries.

\begin{excdesc} {name} \end{excdesc}: Describe an exception. This may be either a string exception or a class exception.

\begin{funcdesc} {name}{parameters} \end{funcdesc}: Describe a module-level function. parameters should not include the parentheses used in the call syntax. Object methods are not documented using this environment. Bound object methods placed in the module namespace as part of the public interface of the module are documented using this, as they are equivalent to normal functions for most purposes.
The description should include information about the parameters required and how they are used (especially whether mutable objects passed as parameters are modified), side effects, and possible exceptions. A small example may be provided.

\begin{funcdescni} {name}{parameters} \end{funcdescni}: Like \funcdesc, but without creating any index entries.

\begin{classdesc} {name}{constructor parameters} \end{classdesc}: Describe a class and its constructor. constructor parameters should not include the self parameter or the parentheses used in the call syntax.

\begin{memberdesc} [type name]{name} \end{memberdesc}: Describe an object data attribute. The description should include information about the type of the data to be expected and whether it may be changed directly.

\begin{memberdescni} [type name]{name} \end{memberdescni}: Like \memberdesc, but without creating any index entries.

\begin{methoddesc} [type name]{name}{parameters} \end{methoddesc}: Describe an object method. parameters should not include the self parameter or the parentheses used in the call syntax. The description should include similar information to that described for \funcdesc.

\begin{methoddescni} [type name]{name}{parameters} \end{methoddescni}: Like \methoddesc, but without creating any index entries.

See About this document... for information on suggesting changes.