<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<!--Converted with LaTeX2HTML 98.2 beta6 (August 14th, 1998)
original version by:  Nikos Drakos, CBLU, University of Leeds
* revised and updated by:  Marcus Hennecke, Ross Moore, Herb Swan
* with significant contributions from:
  Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
<HTML>
<HEAD>
<TITLE>5.1 Information Units </TITLE>
<META NAME="description" CONTENT="5.1 Information Units ">
<META NAME="keywords" CONTENT="doc">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
<LINK REL="STYLESHEET" HREF="doc.css">
<LINK REL="next" HREF="node8.html">
<LINK REL="previous" HREF="node6.html">
<LINK REL="up" HREF="node6.html">
<LINK REL="next" HREF="node8.html">
</HEAD>
<BODY bgcolor="#ffffff">
<div class=navigation>
<table align=center width="100%" cellpadding=0 cellspacing=2>
<tr>
<td><A HREF="node8.html"><img width=32 height=32 align=bottom border=0 alt="next"
 src="../icons/next.gif"></A></td>
<td><A HREF="node6.html"><img width=32 height=32 align=bottom border=0 alt="up"
 src="../icons/up.gif"></A></td>
<td><A HREF="node6.html"><img width=32 height=32 align=bottom border=0 alt="previous"
 src="../icons/previous.gif"></A></td>
<td align=center bgcolor="#99CCFF" width="100%">
 <b class=title>Documenting Python</b></td>
<td><A HREF="contents.html"><img width=32 height=32 align=bottom border=0 alt="contents"
 src="../icons/contents.gif"></A></td>
<td><img width=32 height=32 align=bottom border=0 alt=""
 src="../icons/blank.gif"></td>
<td><img width=32 height=32 align=bottom border=0 alt=""
 src="../icons/blank.gif"></td>
</tr></table><b class=navlabel>Next:</b> <span class=sectref><A HREF="node8.html">5.2 Inline Markup</A></span>
<b class=navlabel>Up:</b> <span class=sectref><A HREF="node6.html">5. Special Markup Constructs</A></span>
<b class=navlabel>Previous:</b> <span class=sectref><A HREF="node6.html">5. Special Markup Constructs</A></span>
<br><hr></div>
<!--End of Navigation Panel-->

<H2><A NAME="SECTION000610000000000000000"></A>
<BR>
5.1 Information Units 
</H2>

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

<P>
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
    <tt><var>feature</var>desc</tt>, and the non-indexing variants are named
    <tt><var>feature</var>descni</tt>.  The available variants are explicitly
    included in the list below.

<P>
For each of these environments, the first parameter, <var>name</var>,
    provides the name by which the feature is accessed.

<P>
Environments which describe features of objects within a module,
    such as object methods or data attributes, allow an optional
    <var>type name</var> parameter.  When the feature is an attribute of
    class instances, <var>type name</var> only needs to be given if the
    class was not the most recently described class in the module; the
    <var>name</var> value from the most recent <tt class=environment>&#92;classdesc</tt> is implied.
    For features of built-in or extension types, the <var>type name</var>
    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
    <tt class=module>formatter</tt> module: these may be documented without any
    specific implementation classes, and will always require the
    <var>type name</var> parameter to be provided.

<P>

<dl class=envdesc>
<dt><tt>&#92;begin{<b class=environment>datadesc</b>}</tt>
    <tt>{</tt><var>name</var><tt>}</tt>
<dd>
      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.
    </dl>
    
<dl class=envdesc>
<dt><tt>&#92;begin{<b class=environment>datadescni</b>}</tt>
    <tt>{</tt><var>name</var><tt>}</tt>
<dd>
      Like <tt class=environment>&#92;datadesc</tt>, but without creating any index entries.
    </dl>

<P>

<dl class=envdesc>
<dt><tt>&#92;begin{<b class=environment>excdesc</b>}</tt>
    <tt>{</tt><var>name</var><tt>}</tt>
<dd>
      Describe an exception.  This may be either a string exception or
      a class exception.
    </dl>

<P>

<dl class=envdesc>
<dt><tt>&#92;begin{<b class=environment>funcdesc</b>}</tt>
    <tt>{</tt><var>name</var><tt>}</tt><tt>{</tt><var>parameters</var><tt>}</tt>
<dd>
      Describe a module-level function.  <var>parameters</var> 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.

<P>
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.
    </dl>
    
<dl class=envdesc>
<dt><tt>&#92;begin{<b class=environment>funcdescni</b>}</tt>
    <tt>{</tt><var>name</var><tt>}</tt><tt>{</tt><var>parameters</var><tt>}</tt>
<dd>
      Like <tt class=environment>&#92;funcdesc</tt>, but without creating any index entries.
    </dl>

<P>

<dl class=envdesc>
<dt><tt>&#92;begin{<b class=environment>classdesc</b>}</tt>
    <tt>{</tt><var>name</var><tt>}</tt><tt>{</tt><var>constructor parameters</var><tt>}</tt>
<dd>
      Describe a class and its constructor.  <var>constructor
      parameters</var> should not include the <var>self</var> parameter or
      the parentheses used in the call syntax.
    </dl>

<P>

<dl class=envdesc>
<dt><tt>&#92;begin{<b class=environment>memberdesc</b>}</tt>
    <tt>[</tt><var>type name</var><tt>]</tt><tt>{</tt><var>name</var><tt>}</tt>
<dd>
      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.
    </dl>
    
<dl class=envdesc>
<dt><tt>&#92;begin{<b class=environment>memberdescni</b>}</tt>
    <tt>[</tt><var>type name</var><tt>]</tt><tt>{</tt><var>name</var><tt>}</tt>
<dd>
      Like <tt class=environment>&#92;memberdesc</tt>, but without creating any index entries.
    </dl>

<P>

<dl class=envdesc>
<dt><tt>&#92;begin{<b class=environment>methoddesc</b>}</tt>
    <tt>[</tt><var>type name</var><tt>]</tt><tt>{</tt><var>name</var><tt>}</tt><tt>{</tt><var>parameters</var><tt>}</tt>
<dd>
      Describe an object method.  <var>parameters</var> should not include
      the <var>self</var> parameter or the parentheses used in the call
      syntax.  The description should include similar information to
      that described for <tt class=environment>&#92;funcdesc</tt>.
    </dl>
    
<dl class=envdesc>
<dt><tt>&#92;begin{<b class=environment>methoddescni</b>}</tt>
    <tt>[</tt><var>type name</var><tt>]</tt><tt>{</tt><var>name</var><tt>}</tt><tt>{</tt><var>parameters</var><tt>}</tt>
<dd>
      Like <tt class=environment>&#92;methoddesc</tt>, but without creating any index entries.
    </dl>

<P>
<p>
<div class=navigation><hr><table align=center width="100%" cellpadding=0 cellspacing=2>
<tr>
<td><A HREF="node8.html"><img width=32 height=32 align=bottom border=0 alt="next"
 src="../icons/next.gif"></A></td>
<td><A HREF="node6.html"><img width=32 height=32 align=bottom border=0 alt="up"
 src="../icons/up.gif"></A></td>
<td><A HREF="node6.html"><img width=32 height=32 align=bottom border=0 alt="previous"
 src="../icons/previous.gif"></A></td>
<td align=center bgcolor="#99CCFF" width="100%">
 <b class=title>Documenting Python</b></td>
<td><A HREF="contents.html"><img width=32 height=32 align=bottom border=0 alt="contents"
 src="../icons/contents.gif"></A></td>
<td><img width=32 height=32 align=bottom border=0 alt=""
 src="../icons/blank.gif"></td>
<td><img width=32 height=32 align=bottom border=0 alt=""
 src="../icons/blank.gif"></td>
</tr></table><b class=navlabel>Next:</b> <span class=sectref><A HREF="node8.html">5.2 Inline Markup</A></span>
<b class=navlabel>Up:</b> <span class=sectref><A HREF="node6.html">5. Special Markup Constructs</A></span>
<b class=navlabel>Previous:</b> <span class=sectref><A HREF="node6.html">5. Special Markup Constructs</A></span>
</div>
<!--End of Navigation Panel-->
<ADDRESS>
<hr>Send comments on this document to <a href="mailto:python-docs@python.org">python-docs@python.org</a>.
</ADDRESS>
</BODY>
</HTML>
