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.
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.
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.
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.
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.
See About this document... for information on suggesting changes.