<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html> <head>
<title>Python Docstrings</title>
<link rel="stylesheet" href="epydoc.css" type="text/css"/>
</head>
<!-- $Id: docstrings.html 1211 2006-04-10 19:38:37Z edloper $ -->
<body>
<div class="body">
<h1> Python Docstrings </h1>
<p> Python documentation strings (or <i>docstrings</i>) 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>
<div class="screen"><pre>
<code class="keyword">def</code> <code class="function">x_intercept</code>(m, b):
<code class="string">"""
Return the x intercept of the line y=m*x+b. The x intercept of a
line is the point at which it crosses the x axis (y=0).
"""</code>
<code class="keyword">return</code> -b/m
</pre></div>
<p> Docstrings can be accessed from the interpreter and from Python
programs using the "<code>__doc__</code>" attribute: </p>
<div class="screen"><pre>
<code class="prompt">>>></code> <code class="user"><code class="keyword">print</code> x_intercept.__doc__</code><code class="output">
Return the x intercept of the line y=m*x+b. The x intercept of a
line is the point at which it crosses the x axis (y=0).</code>
</pre></div>
<p> The <a href="http://web.lfw.org/python/pydoc.html">pydoc</a>
module, which became part of <a
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>
<div class="screen"><pre>
<code class="prompt">>>></code> <code class="user"><code class="keyword">from</code> pydoc <code class="keyword">import</code> help</code>
<code class="prompt">>>></code> <code class="user">help(x_intercept)</code>
<code class="output">Help on function x_intercept in module __main__:
<b>x_intercept</b>(m, b)
Return the x intercept of the line y=m*x+b. The x intercept of a
line is the point at which it crosses the x axis (y=0).</code>
</pre></div>
<p> For more information about Python docstrings, see the <a
href="http://www.python.org/doc/current/tut/node6.html#SECTION006750000000000000000">Python
Tutorial</a> or the Oreilly Network article <a
href="http://www.onlamp.com/lpt/a/python/2001/05/17/docstrings.html">Python
Documentation Tips and Tricks</a>. </p>
</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>
