File: //usr/share/doc/python-docs-2.4.3/html/doc/info-units.html
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="doc.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index' />
<link rel="first" href="doc.html" title='Documenting Python' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="showing-examples.html" />
<link rel="prev" href="meta-info.html" />
<link rel="parent" href="special-constructs.html" />
<link rel="next" href="showing-examples.html" />
<meta name='aesop' content='information' />
<title>6.3 Information Units </title>
</head>
<body>
<DIV CLASS="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="6.2 Meta-information Markup"
href="meta-info.html"><img src='../icons/previous.png'
border='0' height='32' alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="6 Special Markup Constructs"
href="special-constructs.html"><img src='../icons/up.png'
border='0' height='32' alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="6.4 Showing Code Examples"
href="showing-examples.html"><img src='../icons/next.png'
border='0' height='32' alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Documenting Python</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
href="contents.html"><img src='../icons/contents.png'
border='0' height='32' alt='Contents' width='32' /></A></td>
<td class='online-navigation'><img src='../icons/blank.png'
border='0' height='32' alt='' width='32' /></td>
<td class='online-navigation'><img src='../icons/blank.png'
border='0' height='32' alt='' width='32' /></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="meta-info.html">6.2 Meta-information Markup</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="special-constructs.html">6 Special Markup Constructs</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="showing-examples.html">6.4 Showing Code Examples</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->
<H2><A NAME="SECTION000730000000000000000"></A><A NAME="info-units"></A>
<BR>
6.3 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
<code><var>feature</var>desc</code>, and the non-indexing variants are named
<code><var>feature</var>descni</code>. 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'>\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>\begin{<b class='environment'>cfuncdesc</b>}</tt>
<tt>{</tt><var>type</var><tt>}</tt><tt>{</tt><var>name</var><tt>}</tt><tt>{</tt><var>args</var><tt>}</tt>
<br /><tt>\end{<b class='environment'>cfuncdesc</b>}</tt></dt>
<dd>
Environment used to described a C function. The <var>type</var>
should be specified as a <tt class="keyword">typedef</tt> name, <code>struct
<var>tag</var></code>, or the name of a primitive type. If it is a pointer
type, the trailing asterisk should not be preceded by a space.
<var>name</var> should be the name of the function (or function-like
pre-processor macro), and <var>args</var> should give the types and
names of the parameters. The names need to be given so they may
be used in the description.
</dd></dl>
<P>
<dl class='envdesc'>
<dt><tt>\begin{<b class='environment'>cmemberdesc</b>}</tt>
<tt>{</tt><var>container</var><tt>}</tt><tt>{</tt><var>type</var><tt>}</tt><tt>{</tt><var>name</var><tt>}</tt>
<br /><tt>\end{<b class='environment'>cmemberdesc</b>}</tt></dt>
<dd>
Description for a structure member. <var>container</var> should be
the <tt class="keyword">typedef</tt> name, if there is one, otherwise if should
be "<tt class="samp">struct <var>tag</var></tt>". The type of the member should given
as <var>type</var>, and the name should be given as <var>name</var>. 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 <tt class='macro'>\member</tt> macro.
</dd></dl>
<P>
<dl class='envdesc'>
<dt><tt>\begin{<b class='environment'>csimplemacrodesc</b>}</tt>
<tt>{</tt><var>name</var><tt>}</tt>
<br /><tt>\end{<b class='environment'>csimplemacrodesc</b>}</tt></dt>
<dd>
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.
</dd></dl>
<P>
<dl class='envdesc'>
<dt><tt>\begin{<b class='environment'>ctypedesc</b>}</tt>
<tt>[</tt><var>tag</var><tt>]</tt><tt>{</tt><var>name</var><tt>}</tt>
<br /><tt>\end{<b class='environment'>ctypedesc</b>}</tt></dt>
<dd>
Environment used to described a C type. The <var>name</var>
parameter should be the <tt class="keyword">typedef</tt> name. If the type is
defined as a <tt class="keyword">struct</tt> without a <tt class="keyword">typedef</tt>,
<var>name</var> should have the form <code>struct <var>tag</var></code>.
<var>name</var> will be added to the index unless <var>tag</var> is
provided, in which case <var>tag</var> will be used instead.
<var>tag</var> should not be used for a <tt class="keyword">typedef</tt> name.
</dd></dl>
<P>
<dl class='envdesc'>
<dt><tt>\begin{<b class='environment'>cvardesc</b>}</tt>
<tt>{</tt><var>type</var><tt>}</tt><tt>{</tt><var>name</var><tt>}</tt>
<br /><tt>\end{<b class='environment'>cvardesc</b>}</tt></dt>
<dd>
Description of a global C variable. <var>type</var> should be the
<tt class="keyword">typedef</tt> name, <code>struct <var>tag</var></code>, or the name of
a primitive type. If variable has a pointer type, the trailing
asterisk should <em>not</em> be preceded by a space.
</dd></dl>
<P>
<dl class='envdesc'>
<dt><tt>\begin{<b class='environment'>datadesc</b>}</tt>
<tt>{</tt><var>name</var><tt>}</tt>
<br /><tt>\end{<b class='environment'>datadesc</b>}</tt></dt>
<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.
</dd></dl>
<dl class='envdesc'>
<dt><tt>\begin{<b class='environment'>datadescni</b>}</tt>
<tt>{</tt><var>name</var><tt>}</tt>
<br /><tt>\end{<b class='environment'>datadescni</b>}</tt></dt>
<dd>
Like <tt class='environment'>\datadesc</tt>, but without creating any index entries.
</dd></dl>
<P>
<dl class='envdesc'>
<dt><tt>\begin{<b class='environment'>excclassdesc</b>}</tt>
<tt>{</tt><var>name</var><tt>}</tt><tt>{</tt><var>constructor parameters</var><tt>}</tt>
<br /><tt>\end{<b class='environment'>excclassdesc</b>}</tt></dt>
<dd>
Describe an exception defined by a class. <var>constructor
parameters</var> should not include the <var>self</var> parameter or
the parentheses used in the call syntax. To describe an
exception class without describing the parameters to its
constructor, use the <tt class='environment'>\excdesc</tt> environment.
</dd></dl>
<P>
<dl class='envdesc'>
<dt><tt>\begin{<b class='environment'>excdesc</b>}</tt>
<tt>{</tt><var>name</var><tt>}</tt>
<br /><tt>\end{<b class='environment'>excdesc</b>}</tt></dt>
<dd>
Describe an exception. In the case of class exceptions, the
constructor parameters are not described; use <tt class='environment'>\excclassdesc</tt>
to describe an exception class and its constructor.
</dd></dl>
<P>
<dl class='envdesc'>
<dt><tt>\begin{<b class='environment'>funcdesc</b>}</tt>
<tt>{</tt><var>name</var><tt>}</tt><tt>{</tt><var>parameters</var><tt>}</tt>
<br /><tt>\end{<b class='environment'>funcdesc</b>}</tt></dt>
<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.
</dd></dl>
<dl class='envdesc'>
<dt><tt>\begin{<b class='environment'>funcdescni</b>}</tt>
<tt>{</tt><var>name</var><tt>}</tt><tt>{</tt><var>parameters</var><tt>}</tt>
<br /><tt>\end{<b class='environment'>funcdescni</b>}</tt></dt>
<dd>
Like <tt class='environment'>\funcdesc</tt>, but without creating any index entries.
</dd></dl>
<P>
<dl class='envdesc'>
<dt><tt>\begin{<b class='environment'>classdesc</b>}</tt>
<tt>{</tt><var>name</var><tt>}</tt><tt>{</tt><var>constructor parameters</var><tt>}</tt>
<br /><tt>\end{<b class='environment'>classdesc</b>}</tt></dt>
<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.
</dd></dl>
<P>
<dl class='envdesc'>
<dt><tt>\begin{<b class='environment'>classdesc*</b>}</tt>
<tt>{</tt><var>name</var><tt>}</tt>
<br /><tt>\end{<b class='environment'>classdesc*</b>}</tt></dt>
<dd>
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.
</dd></dl>
<P>
<dl class='envdesc'>
<dt><tt>\begin{<b class='environment'>memberdesc</b>}</tt>
<tt>[</tt><var>type name</var><tt>]</tt><tt>{</tt><var>name</var><tt>}</tt>
<br /><tt>\end{<b class='environment'>memberdesc</b>}</tt></dt>
<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.
</dd></dl>
<dl class='envdesc'>
<dt><tt>\begin{<b class='environment'>memberdescni</b>}</tt>
<tt>[</tt><var>type name</var><tt>]</tt><tt>{</tt><var>name</var><tt>}</tt>
<br /><tt>\end{<b class='environment'>memberdescni</b>}</tt></dt>
<dd>
Like <tt class='environment'>\memberdesc</tt>, but without creating any index entries.
</dd></dl>
<P>
<dl class='envdesc'>
<dt><tt>\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>
<br /><tt>\end{<b class='environment'>methoddesc</b>}</tt></dt>
<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'>\funcdesc</tt>.
</dd></dl>
<dl class='envdesc'>
<dt><tt>\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>
<br /><tt>\end{<b class='environment'>methoddescni</b>}</tt></dt>
<dd>
Like <tt class='environment'>\methoddesc</tt>, but without creating any index entries.
</dd></dl>
<P>
<DIV CLASS="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="6.2 Meta-information Markup"
href="meta-info.html"><img src='../icons/previous.png'
border='0' height='32' alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="6 Special Markup Constructs"
href="special-constructs.html"><img src='../icons/up.png'
border='0' height='32' alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="6.4 Showing Code Examples"
href="showing-examples.html"><img src='../icons/next.png'
border='0' height='32' alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Documenting Python</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
href="contents.html"><img src='../icons/contents.png'
border='0' height='32' alt='Contents' width='32' /></A></td>
<td class='online-navigation'><img src='../icons/blank.png'
border='0' height='32' alt='' width='32' /></td>
<td class='online-navigation'><img src='../icons/blank.png'
border='0' height='32' alt='' width='32' /></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="meta-info.html">6.2 Meta-information Markup</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="special-constructs.html">6 Special Markup Constructs</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="showing-examples.html">6.4 Showing Code Examples</A>
</div>
</div>
<hr />
<span class="release-info">Release 2.4.3, documentation updated on 29 March 2006.</span>
</DIV>
<!--End of Navigation Panel-->
<ADDRESS>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</ADDRESS>
</BODY>
</HTML>