6.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{cmemberdesc}
    {container}{type}{name}
 \end{cmemberdesc}
- 
      Description for a structure member.  container should be
      the typedef name, if there is one, otherwise if should
      be "struct tag".  The type of the member should given
      as type, and the name should be given as name.  The
      text of the description should include the range of values
      allowed, how the value should be interpreted, and whether the
      value can be changed.  References to structure members in text
      should use the \member macro.
    
- \begin{csimplemacrodesc}
    {name}
 \end{csimplemacrodesc}
- 
      Documentation for a ``simple'' macro.  Simple macros are macros
      which are used for code expansion, but which do not take
      arguments so cannot be described as functions.  This is not to
      be used for simple constant definitions.  Examples of it's use
      in the Python documentation include
      PyObject_HEAD and
      Py_BEGIN_ALLOW_THREADS.
    
- \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{excclassdesc}
    {name}{constructor parameters}
 \end{excclassdesc}
- 
      Describe an exception defined by a class.  constructor
      parameters should not include the self parameter or
      the parentheses used in the call syntax.  To describe an
      exception class without describing the parameters to its
      constructor, use the \excdesc environment.
    
- \begin{excdesc}
    {name}
 \end{excdesc}
- 
      Describe an exception.  In the case of class exceptions, the
      constructor parameters are not described; use \excclassdesc
      to describe an exception class and its constructor.
    
- \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{classdesc*}
    {name}
 \end{classdesc*}
- 
      Describe a class without describing the constructor.  This can
      be used to describe classes that are merely containers for
      attributes or which should never be instantiated or subclassed
      by user code.
    
- \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.
    
Release 2.4.3, documentation updated on 29 March 2006.
 
See About this document... for information on suggesting changes.