<?xml version="1.0" encoding="ascii" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ascii" />
<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
<title>Python Docstrings</title>
<link rel="stylesheet" href="custom.css" type="text/css" />
</head>
<body>
<div class="document" id="python-docstrings">
<h1 class="title">Python Docstrings</h1>
<!-- $Id: manual-docstring.txt 1575 2007-03-08 21:28:07Z edloper $ -->
<p>Python documentation strings (or <em>docstrings</em>) provide a convenient way of
associating documentation with Python modules, functions, classes, and methods.
An object's docsting is defined by including a string constant as the first
statement in the object's definition. For example, the following function
defines a docstring:</p>
<pre class="py-doctest">
<span class="py-keyword">def</span> <span class="py-defname">x_intercept</span>(m, b):
<span class="py-string">"""</span>
<span class="py-string"> Return the x intercept of the line y=m*x+b. The x intercept of a</span>
<span class="py-string"> line is the point at which it crosses the x axis (y=0).</span>
<span class="py-string"> """</span>
return -b/m</pre>
<p>Docstrings can be accessed from the interpreter and from Python programs
using the "<tt class="docutils literal"><span class="pre">__doc__</span></tt>" attribute:</p>
<pre class="py-doctest">
<span class="py-prompt">>>> </span><span class="py-keyword">print</span> x_intercept.__doc__
Return the x intercept of the line y=m*x+b. The x intercept of a
line <span class="py-keyword">is</span> the point at which it crosses the x axis (y=0).</pre>
<p>The <a class="reference external" href="http://web.lfw.org/python/pydoc.html">pydoc</a> module, which became part of <a class="reference external" href="http://www.python.org/doc/current/lib/module-pydoc.html">the standard library</a> in Python 2.1,
can be used to display information about a Python object, including its
docstring:</p>
<pre class="py-doctest">
<span class="py-prompt">>>> </span><span class="py-keyword">from</span> pydoc <span class="py-keyword">import</span> help
<span class="py-prompt">>>> </span>help(x_intercept)
Help on function x_intercept <span class="py-keyword">in</span> module __main__:
x_intercept(m, b)
Return the x intercept of the line y=m*x+b. The x intercept of a
line <span class="py-keyword">is</span> the point at which it crosses the x axis (y=0).</pre>
<p>For more information about Python docstrings, see the <a class="reference external" href="http://www.python.org/doc/current/tut/node6.html#docstrings">Python Tutorial</a> or
the O'Reilly Network article <a class="reference external" href="http://www.onlamp.com/lpt/a/python/2001/05/17/docstrings.html">Python Documentation Tips and Tricks</a>.</p>
<div class="section" id="variable-docstrings">
<h1>Variable docstrings</h1>
<!-- [xx] this should be somewhere else, i guess... -->
<p>Python don't support directly docstrings on variables: there is no attribute
that can be attached to variables and retrieved interactively like the
<tt class="docutils literal"><span class="pre">__doc__</span></tt> attribute on modules, classes and functions.</p>
<p>While the language doesn't directly provides for them, Epydoc supports
<em>variable docstrings</em>: if a variable assignment statement is immediately
followed by a bare string literal, then that assignment is treated as a
docstring for that variable. In classes, variable assignments at the class
definition level are considered class variables; and assignments to instance
variables in the constructor (<tt class="docutils literal"><span class="pre">__init__</span></tt>) are considered instance variables:</p>
<pre class="py-doctest">
<span class="py-keyword">class</span> <span class="py-defname">A</span>:
x = 22
<span class="py-string">"""Docstring for class variable A.x"""</span>
<span class="py-keyword">def</span> <span class="py-defname">__init__</span>(self, a):
self.y = a
<span class="py-string">""</span>"Docstring <span class="py-keyword">for</span> instance variable A.y</pre>
<p>Variables may also be documented using <em>comment docstrings</em>. If a variable
assignment is immediately preceeded by a comment whose lines begin with the
special marker '<tt class="docutils literal"><span class="pre">#:</span></tt>', or is followed on the same line by such a comment,
then it is treated as a docstring for that variable:</p>
<pre class="py-doctest">
<span class="py-comment">#: docstring for x</span>
x = 22
x = 22 <span class="py-comment">#: docstring for x</span></pre>
<p>Notice that variable docstrings are only available for documentation when the
source code is available for <em>parsing</em>: it is not possible to retrieve variable</p>
</div>
<div class="section" id="items-visibility">
<h1>Items visibility</h1>
<p>Any Python object (modules, classes, functions, variables...) can be <em>public</em>
or <em>private</em>. Usually the object name decides the object visibility: objects
whose name starts with an underscore and doesn't end with an underscore are
considered private. All the other objects (including the "magic functions" such
as <tt class="docutils literal"><span class="pre">__add__</span></tt>) are public.</p>
<p>For each module and class, Epydoc generates pages with both public and private
methods. A Javascript snippet allows you to toggle the visibility of private
objects.</p>
<p>If a module wants to hide some of the objects it contains (either defined in
the module itself or imported from other modules), it can explicitly list the
names if its <a class="reference external" href="http://www.python.org/doc/2.4.3/ref/import.html">public names</a> in the <tt class="docutils literal"><span class="pre">__all__</span></tt> variable.</p>
<p>If a module defines the <tt class="docutils literal"><span class="pre">__all__</span></tt> variable, Epydoc uses its content to decide
if the module objects are public or private.</p>
</div>
</div>
<table width="100%" class="navbox" cellpadding="1" cellspacing="0">
<tr>
<a class="nav" href="index.html">
<td align="center" width="20%" class="nav">
<a class="nav" href="index.html">
Home</a></td></a>
<a class="nav" href="installing.html">
<td align="center" width="20%" class="nav">
<a class="nav" href="installing.html">
Installing Epydoc</a></td></a>
<a class="nav" href="using.html">
<td align="center" width="20%" class="nav">
<a class="nav" href="using.html">
Using Epydoc</a></td></a>
<a class="nav" href="epytext.html">
<td align="center" width="20%" class="nav">
<a class="nav" href="epytext.html">
Epytext</a></td></a>
<td align="center" width="20%" class="nav">
<A href="http://sourceforge.net/projects/epydoc">
<IMG src="sflogo.png"
width="88" height="26" border="0" alt="SourceForge"
align="top"/></A></td>
</tr>
</table>
</body>
</html>
