[OpenSPARC-T2-SAM] / sam-t2 / devtools / v8plus / html / python / 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'>&#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'>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>&#92;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>&#92;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>&#92;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'>&#92;member</tt> macro.
    </dd></dl>

<P>

<dl class='envdesc'>
<dt><tt>&#92;begin{<b class='environment'>csimplemacrodesc</b>}</tt>
    <tt>{</tt><var>name</var><tt>}</tt>
<br /><tt>&#92;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>&#92;begin{<b class='environment'>ctypedesc</b>}</tt>
    <tt>[</tt><var>tag</var><tt>]</tt><tt>{</tt><var>name</var><tt>}</tt>
<br /><tt>&#92;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>&#92;begin{<b class='environment'>cvardesc</b>}</tt>
    <tt>{</tt><var>type</var><tt>}</tt><tt>{</tt><var>name</var><tt>}</tt>
<br /><tt>&#92;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>&#92;begin{<b class='environment'>datadesc</b>}</tt>
    <tt>{</tt><var>name</var><tt>}</tt>
<br /><tt>&#92;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>&#92;begin{<b class='environment'>datadescni</b>}</tt>
    <tt>{</tt><var>name</var><tt>}</tt>
<br /><tt>&#92;end{<b class='environment'>datadescni</b>}</tt></dt>
<dd>
      Like <tt class='environment'>&#92;datadesc</tt>, but without creating any index entries.
    </dd></dl>

<P>

<dl class='envdesc'>
<dt><tt>&#92;begin{<b class='environment'>excclassdesc</b>}</tt>
    <tt>{</tt><var>name</var><tt>}</tt><tt>{</tt><var>constructor parameters</var><tt>}</tt>
<br /><tt>&#92;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'>&#92;excdesc</tt> environment.
    </dd></dl>

<P>

<dl class='envdesc'>
<dt><tt>&#92;begin{<b class='environment'>excdesc</b>}</tt>
    <tt>{</tt><var>name</var><tt>}</tt>
<br /><tt>&#92;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'>&#92;excclassdesc</tt>
      to describe an exception class and its constructor.
    </dd></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>
<br /><tt>&#92;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>&#92;begin{<b class='environment'>funcdescni</b>}</tt>
    <tt>{</tt><var>name</var><tt>}</tt><tt>{</tt><var>parameters</var><tt>}</tt>
<br /><tt>&#92;end{<b class='environment'>funcdescni</b>}</tt></dt>
<dd>
      Like <tt class='environment'>&#92;funcdesc</tt>, but without creating any index entries.
    </dd></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>
<br /><tt>&#92;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>&#92;begin{<b class='environment'>classdesc*</b>}</tt>
    <tt>{</tt><var>name</var><tt>}</tt>
<br /><tt>&#92;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>&#92;begin{<b class='environment'>memberdesc</b>}</tt>
    <tt>[</tt><var>type name</var><tt>]</tt><tt>{</tt><var>name</var><tt>}</tt>
<br /><tt>&#92;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>&#92;begin{<b class='environment'>memberdescni</b>}</tt>
    <tt>[</tt><var>type name</var><tt>]</tt><tt>{</tt><var>name</var><tt>}</tt>
<br /><tt>&#92;end{<b class='environment'>memberdescni</b>}</tt></dt>
<dd>
      Like <tt class='environment'>&#92;memberdesc</tt>, but without creating any index entries.
    </dd></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>
<br /><tt>&#92;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'>&#92;funcdesc</tt>.
    </dd></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>
<br /><tt>&#92;end{<b class='environment'>methoddescni</b>}</tt></dt>
<dd>
      Like <tt class='environment'>&#92;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.2, documentation updated on 28 September 2005.</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>
Commit	Line	Data
920dae64 AT	1	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
	2	<html>
	3	<head>
	4	<link rel="STYLESHEET" href="doc.css" type='text/css' />
	5	<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
	6	<link rel='start' href='../index.html' title='Python Documentation Index' />
	7	<link rel="first" href="doc.html" title='Documenting Python' />
	8	<link rel='contents' href='contents.html' title="Contents" />
	9	<link rel='last' href='about.html' title='About this document...' />
	10	<link rel='help' href='about.html' title='About this document...' />
	11	<link rel="next" href="showing-examples.html" />
	12	<link rel="prev" href="meta-info.html" />
	13	<link rel="parent" href="special-constructs.html" />
	14	<link rel="next" href="showing-examples.html" />
	15	<meta name='aesop' content='information' />
	16	<title>6.3 Information Units </title>
	17	</head>
	18	<body>
	19	<DIV CLASS="navigation">
	20	<div id='top-navigation-panel' xml:id='top-navigation-panel'>
	21	<table align="center" width="100%" cellpadding="0" cellspacing="2">
	22	<tr>
	23	<td class='online-navigation'><a rel="prev" title="6.2 Meta-information Markup"
	24	href="meta-info.html"><img src='../icons/previous.png'
	25	border='0' height='32' alt='Previous Page' width='32' /></A></td>
	26	<td class='online-navigation'><a rel="parent" title="6 Special Markup Constructs"
	27	href="special-constructs.html"><img src='../icons/up.png'
	28	border='0' height='32' alt='Up One Level' width='32' /></A></td>
	29	<td class='online-navigation'><a rel="next" title="6.4 Showing Code Examples"
	30	href="showing-examples.html"><img src='../icons/next.png'
	31	border='0' height='32' alt='Next Page' width='32' /></A></td>
	32	<td align="center" width="100%">Documenting Python</td>
	33	<td class='online-navigation'><a rel="contents" title="Table of Contents"
	34	href="contents.html"><img src='../icons/contents.png'
	35	border='0' height='32' alt='Contents' width='32' /></A></td>
	36	<td class='online-navigation'><img src='../icons/blank.png'
	37	border='0' height='32' alt='' width='32' /></td>
	38	<td class='online-navigation'><img src='../icons/blank.png'
	39	border='0' height='32' alt='' width='32' /></td>
	40	</tr></table>
	41	<div class='online-navigation'>
	42	<b class="navlabel">Previous:</b>
	43	<a class="sectref" rel="prev" href="meta-info.html">6.2 Meta-information Markup</A>
	44	<b class="navlabel">Up:</b>
	45	<a class="sectref" rel="parent" href="special-constructs.html">6 Special Markup Constructs</A>
	46	<b class="navlabel">Next:</b>
	47	<a class="sectref" rel="next" href="showing-examples.html">6.4 Showing Code Examples</A>
	48	</div>
	49	<hr /></div>
	50	</DIV>
	51	<!--End of Navigation Panel-->
	52
	53	<H2><A NAME="SECTION000730000000000000000"></A><A NAME="info-units"></A>
	54	<BR>
	55	6.3 Information Units
	56	</H2>
	57
	58	<P>
	59	XXX Explain terminology, or come up with something more ``lay.''
	60
	61	<P>
	62	There are a number of environments used to describe specific
	63	features provided by modules. Each environment requires
	64	parameters needed to provide basic information about what is being
65	described, and the environment content should be the description.
66	Most of these environments make entries in the general index (if
67	one is being produced for the document); if no index entry is
68	desired, non-indexing variants are available for many of these
69	environments. The environments have names of the form
70	<code><var>feature</var>desc</code>, and the non-indexing variants are named
71	<code><var>feature</var>descni</code>. The available variants are explicitly
72	included in the list below.
73
74	<P>
75	For each of these environments, the first parameter, <var>name</var>,
76	provides the name by which the feature is accessed.
77
78	<P>
79	Environments which describe features of objects within a module,
80	such as object methods or data attributes, allow an optional
81	<var>type name</var> parameter. When the feature is an attribute of
82	class instances, <var>type name</var> only needs to be given if the
83	class was not the most recently described class in the module; the
84	<var>name</var> value from the most recent <tt class='environment'>\classdesc</tt> is implied.
85	For features of built-in or extension types, the <var>type name</var>
86	value should always be provided. Another special case includes
87	methods and members of general ``protocols,'' such as the
88	formatter and writer protocols described for the
89	<tt class="module">formatter</tt> module: these may be documented without any
90	specific implementation classes, and will always require the
91	<var>type name</var> parameter to be provided.
92
93	<P>
94
95	<dl class='envdesc'>
96	<dt><tt>\begin{<b class='environment'>cfuncdesc</b>}</tt>
97	<tt>{</tt><var>type</var><tt>}</tt><tt>{</tt><var>name</var><tt>}</tt><tt>{</tt><var>args</var><tt>}</tt>
98	<br /><tt>\end{<b class='environment'>cfuncdesc</b>}</tt></dt>
99	<dd>
100	Environment used to described a C function. The <var>type</var>
101	should be specified as a <tt class="keyword">typedef</tt> name, <code>struct
102	<var>tag</var></code>, or the name of a primitive type. If it is a pointer
103	type, the trailing asterisk should not be preceded by a space.
104	<var>name</var> should be the name of the function (or function-like
105	pre-processor macro), and <var>args</var> should give the types and
106	names of the parameters. The names need to be given so they may
107	be used in the description.
108	</dd></dl>
109
110	<P>
111
112	<dl class='envdesc'>
113	<dt><tt>\begin{<b class='environment'>cmemberdesc</b>}</tt>
114	<tt>{</tt><var>container</var><tt>}</tt><tt>{</tt><var>type</var><tt>}</tt><tt>{</tt><var>name</var><tt>}</tt>
115	<br /><tt>\end{<b class='environment'>cmemberdesc</b>}</tt></dt>
116	<dd>
117	Description for a structure member. <var>container</var> should be
118	the <tt class="keyword">typedef</tt> name, if there is one, otherwise if should
119	be "<tt class="samp">struct <var>tag</var></tt>". The type of the member should given
120	as <var>type</var>, and the name should be given as <var>name</var>. The
121	text of the description should include the range of values
122	allowed, how the value should be interpreted, and whether the
123	value can be changed. References to structure members in text
124	should use the <tt class='macro'>\member</tt> macro.
125	</dd></dl>
126
127	<P>
128
129	<dl class='envdesc'>
130	<dt><tt>\begin{<b class='environment'>csimplemacrodesc</b>}</tt>
131	<tt>{</tt><var>name</var><tt>}</tt>
132	<br /><tt>\end{<b class='environment'>csimplemacrodesc</b>}</tt></dt>
133	<dd>
134	Documentation for a ``simple'' macro. Simple macros are macros
135	which are used for code expansion, but which do not take
136	arguments so cannot be described as functions. This is not to
137	be used for simple constant definitions. Examples of it's use
138	in the Python documentation include
139	PyObject_HEAD and
140	Py_BEGIN_ALLOW_THREADS.
141	</dd></dl>
142
143	<P>
144
145	<dl class='envdesc'>
146	<dt><tt>\begin{<b class='environment'>ctypedesc</b>}</tt>
147	<tt>[</tt><var>tag</var><tt>]</tt><tt>{</tt><var>name</var><tt>}</tt>
148	<br /><tt>\end{<b class='environment'>ctypedesc</b>}</tt></dt>
149	<dd>
150	Environment used to described a C type. The <var>name</var>
151	parameter should be the <tt class="keyword">typedef</tt> name. If the type is
152	defined as a <tt class="keyword">struct</tt> without a <tt class="keyword">typedef</tt>,
153	<var>name</var> should have the form <code>struct <var>tag</var></code>.
154	<var>name</var> will be added to the index unless <var>tag</var> is
155	provided, in which case <var>tag</var> will be used instead.
156	<var>tag</var> should not be used for a <tt class="keyword">typedef</tt> name.
157	</dd></dl>
158
159	<P>
160
161	<dl class='envdesc'>
162	<dt><tt>\begin{<b class='environment'>cvardesc</b>}</tt>
163	<tt>{</tt><var>type</var><tt>}</tt><tt>{</tt><var>name</var><tt>}</tt>
164	<br /><tt>\end{<b class='environment'>cvardesc</b>}</tt></dt>
165	<dd>
166	Description of a global C variable. <var>type</var> should be the
167	<tt class="keyword">typedef</tt> name, <code>struct <var>tag</var></code>, or the name of
168	a primitive type. If variable has a pointer type, the trailing
169	asterisk should <em>not</em> be preceded by a space.
170	</dd></dl>
171
172	<P>
173
174	<dl class='envdesc'>
175	<dt><tt>\begin{<b class='environment'>datadesc</b>}</tt>
176	<tt>{</tt><var>name</var><tt>}</tt>
177	<br /><tt>\end{<b class='environment'>datadesc</b>}</tt></dt>
178	<dd>
179	This environment is used to document global data in a module,
180	including both variables and values used as ``defined
181	constants.'' Class and object attributes are not documented
182	using this environment.
183	</dd></dl>
184
185	<dl class='envdesc'>
186	<dt><tt>\begin{<b class='environment'>datadescni</b>}</tt>
187	<tt>{</tt><var>name</var><tt>}</tt>
188	<br /><tt>\end{<b class='environment'>datadescni</b>}</tt></dt>
189	<dd>
190	Like <tt class='environment'>\datadesc</tt>, but without creating any index entries.
191	</dd></dl>
192
193	<P>
194
195	<dl class='envdesc'>
196	<dt><tt>\begin{<b class='environment'>excclassdesc</b>}</tt>
197	<tt>{</tt><var>name</var><tt>}</tt><tt>{</tt><var>constructor parameters</var><tt>}</tt>
198	<br /><tt>\end{<b class='environment'>excclassdesc</b>}</tt></dt>
199	<dd>
200	Describe an exception defined by a class. <var>constructor
201	parameters</var> should not include the <var>self</var> parameter or
202	the parentheses used in the call syntax. To describe an
203	exception class without describing the parameters to its
204	constructor, use the <tt class='environment'>\excdesc</tt> environment.
205	</dd></dl>
206
207	<P>
208
209	<dl class='envdesc'>
210	<dt><tt>\begin{<b class='environment'>excdesc</b>}</tt>
211	<tt>{</tt><var>name</var><tt>}</tt>
212	<br /><tt>\end{<b class='environment'>excdesc</b>}</tt></dt>
213	<dd>
214	Describe an exception. In the case of class exceptions, the
215	constructor parameters are not described; use <tt class='environment'>\excclassdesc</tt>
216	to describe an exception class and its constructor.
217	</dd></dl>
218
219	<P>
220
221	<dl class='envdesc'>
222	<dt><tt>\begin{<b class='environment'>funcdesc</b>}</tt>
223	<tt>{</tt><var>name</var><tt>}</tt><tt>{</tt><var>parameters</var><tt>}</tt>
224	<br /><tt>\end{<b class='environment'>funcdesc</b>}</tt></dt>
225	<dd>
226	Describe a module-level function. <var>parameters</var> should
227	not include the parentheses used in the call syntax. Object
228	methods are not documented using this environment. Bound object
229	methods placed in the module namespace as part of the public
230	interface of the module are documented using this, as they are
231	equivalent to normal functions for most purposes.
232
233	<P>
234	The description should include information about the parameters
235	required and how they are used (especially whether mutable
236	objects passed as parameters are modified), side effects, and
237	possible exceptions. A small example may be provided.
238	</dd></dl>
239
240	<dl class='envdesc'>
241	<dt><tt>\begin{<b class='environment'>funcdescni</b>}</tt>
242	<tt>{</tt><var>name</var><tt>}</tt><tt>{</tt><var>parameters</var><tt>}</tt>
243	<br /><tt>\end{<b class='environment'>funcdescni</b>}</tt></dt>
244	<dd>
245	Like <tt class='environment'>\funcdesc</tt>, but without creating any index entries.
246	</dd></dl>
247
248	<P>
249
250	<dl class='envdesc'>
251	<dt><tt>\begin{<b class='environment'>classdesc</b>}</tt>
252	<tt>{</tt><var>name</var><tt>}</tt><tt>{</tt><var>constructor parameters</var><tt>}</tt>
253	<br /><tt>\end{<b class='environment'>classdesc</b>}</tt></dt>
254	<dd>
255	Describe a class and its constructor. <var>constructor
256	parameters</var> should not include the <var>self</var> parameter or
257	the parentheses used in the call syntax.
258	</dd></dl>
259
260	<P>
261
262	<dl class='envdesc'>
263	<dt><tt>\begin{<b class='environment'>classdesc*</b>}</tt>
264	<tt>{</tt><var>name</var><tt>}</tt>
265	<br /><tt>\end{<b class='environment'>classdesc*</b>}</tt></dt>
266	<dd>
267	Describe a class without describing the constructor. This can
268	be used to describe classes that are merely containers for
269	attributes or which should never be instantiated or subclassed
270	by user code.
271	</dd></dl>
272
273	<P>
274
275	<dl class='envdesc'>
276	<dt><tt>\begin{<b class='environment'>memberdesc</b>}</tt>
277	<tt>[</tt><var>type name</var><tt>]</tt><tt>{</tt><var>name</var><tt>}</tt>
278	<br /><tt>\end{<b class='environment'>memberdesc</b>}</tt></dt>
279	<dd>
280	Describe an object data attribute. The description should
281	include information about the type of the data to be expected
282	and whether it may be changed directly.
283	</dd></dl>
284
285	<dl class='envdesc'>
286	<dt><tt>\begin{<b class='environment'>memberdescni</b>}</tt>
287	<tt>[</tt><var>type name</var><tt>]</tt><tt>{</tt><var>name</var><tt>}</tt>
288	<br /><tt>\end{<b class='environment'>memberdescni</b>}</tt></dt>
289	<dd>
290	Like <tt class='environment'>\memberdesc</tt>, but without creating any index entries.
291	</dd></dl>
292
293	<P>
294
295	<dl class='envdesc'>
296	<dt><tt>\begin{<b class='environment'>methoddesc</b>}</tt>
297	<tt>[</tt><var>type name</var><tt>]</tt><tt>{</tt><var>name</var><tt>}</tt><tt>{</tt><var>parameters</var><tt>}</tt>
298	<br /><tt>\end{<b class='environment'>methoddesc</b>}</tt></dt>
299	<dd>
300	Describe an object method. <var>parameters</var> should not include
301	the <var>self</var> parameter or the parentheses used in the call
302	syntax. The description should include similar information to
303	that described for <tt class='environment'>\funcdesc</tt>.
304	</dd></dl>
305
306	<dl class='envdesc'>
307	<dt><tt>\begin{<b class='environment'>methoddescni</b>}</tt>
308	<tt>[</tt><var>type name</var><tt>]</tt><tt>{</tt><var>name</var><tt>}</tt><tt>{</tt><var>parameters</var><tt>}</tt>
309	<br /><tt>\end{<b class='environment'>methoddescni</b>}</tt></dt>
310	<dd>
311	Like <tt class='environment'>\methoddesc</tt>, but without creating any index entries.
312	</dd></dl>
313
314	<P>
315
316	<DIV CLASS="navigation">
317	<div class='online-navigation'>
318	<p></p><hr />
319	<table align="center" width="100%" cellpadding="0" cellspacing="2">
320	<tr>
321	<td class='online-navigation'><a rel="prev" title="6.2 Meta-information Markup"
322	href="meta-info.html"><img src='../icons/previous.png'
323	border='0' height='32' alt='Previous Page' width='32' /></A></td>
324	<td class='online-navigation'><a rel="parent" title="6 Special Markup Constructs"
325	href="special-constructs.html"><img src='../icons/up.png'
326	border='0' height='32' alt='Up One Level' width='32' /></A></td>
327	<td class='online-navigation'><a rel="next" title="6.4 Showing Code Examples"
328	href="showing-examples.html"><img src='../icons/next.png'
329	border='0' height='32' alt='Next Page' width='32' /></A></td>
330	<td align="center" width="100%">Documenting Python</td>
331	<td class='online-navigation'><a rel="contents" title="Table of Contents"
332	href="contents.html"><img src='../icons/contents.png'
333	border='0' height='32' alt='Contents' width='32' /></A></td>
334	<td class='online-navigation'><img src='../icons/blank.png'
335	border='0' height='32' alt='' width='32' /></td>
336	<td class='online-navigation'><img src='../icons/blank.png'
337	border='0' height='32' alt='' width='32' /></td>
338	</tr></table>
339	<div class='online-navigation'>
340	<b class="navlabel">Previous:</b>
341	<a class="sectref" rel="prev" href="meta-info.html">6.2 Meta-information Markup</A>
342	<b class="navlabel">Up:</b>
343	<a class="sectref" rel="parent" href="special-constructs.html">6 Special Markup Constructs</A>
344	<b class="navlabel">Next:</b>
345	<a class="sectref" rel="next" href="showing-examples.html">6.4 Showing Code Examples</A>
346	</div>
347	</div>
348	<hr />
349	<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
350	</DIV>
351	<!--End of Navigation Panel-->
352	<ADDRESS>
353	See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
354	</ADDRESS>
355	</BODY>
356	</HTML>