5.2 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.
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.
Like \datadesc, but without creating any index entries.
Describe an exception. This may be either a string exception or
a class exception.
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.
Like \funcdesc, but without creating any index entries.
Describe a class and its constructor. constructor
parameters should not include the self parameter or
the parentheses used in the call syntax.
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.
Like \memberdesc, but without creating any index entries.
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.
Like \methoddesc, but without creating any index entries.
Send comments on this document to firstname.lastname@example.org.