[Epydoc-commits] SF.net SVN: epydoc: [1548] trunk/epydoc/doc
Brought to you by:
edloper
Menu
▾
▴
[Epydoc-commits] SF.net SVN: epydoc: [1548] trunk/epydoc/doc
|
From: <dva...@us...> - 2007-02-22 00:25:44
|
Revision: 1548
http://svn.sourceforge.net/epydoc/?rev=1548&view=rev
Author: dvarrazzo
Date: 2007-02-21 16:25:40 -0800 (Wed, 21 Feb 2007)
Log Message:
-----------
- Some manual fixes
- Manual on the homepage.
Modified Paths:
--------------
trunk/epydoc/doc/index.html
trunk/epydoc/doc/manual-docstring.txt
trunk/epydoc/doc/manual-fields.txt
trunk/epydoc/doc/manual.txt
Modified: trunk/epydoc/doc/index.html
===================================================================
--- trunk/epydoc/doc/index.html 2007-02-21 17:34:54 UTC (rev 1547)
+++ trunk/epydoc/doc/index.html 2007-02-22 00:25:40 UTC (rev 1548)
@@ -38,20 +38,20 @@
<p><b>Using Epydoc</b>
<ul class="nomargin">
- <li><a href="installing.html">Installing Epydoc</a> </li>
- <li><a href="using.html">Using Epydoc</a> </li>
+ <li><a href="epydoc.html">Epydoc manual</a> </li>
<li><a href="faq.html">Frequently Asked Questions</a>
<li><a href="api/">API Documentation</a></li>
</ul></p>
-<p><b>Docstring Markup</b>
+<p><b>Manual Chapters</b>
<ul class="nomargin">
- <li> <a href="docstrings.html">Python Docstrings</a> </li>
- <li> <a href="epytextintro.html">Introduction to
- Epytext Markup</a> </li>
- <li> <a href="epytext.html">Epytext Markup Language Manual</a> </li>
- <li> <a href="othermarkup.html">ReStructuredText and Javadoc</a> </li>
- <li> <a href="fields.html">Epydoc Fields</a> </li>
+ <li> <a href="manual-install.html">Installing Epydoc</a> </li>
+ <li> <a href="manual-usage.html">Using Epydoc</a> </li>
+ <li> <a href="manual-docstrings.html">Python Docstrings</a> </li>
+ <li> <a href="manual-epytext.html">The Epytext Markup Language</a> </li>
+ <li> <a href="manual-fields.html">Epydoc Fields</a> </li>
+ <li> <a href="manual-othermarkup.html">reStructuredText and Javadoc</a> </li>
+ <li> <a href="manual-reference.html">References</a> </li>
</ul></p>
</td><td class="transparent">
Modified: trunk/epydoc/doc/manual-docstring.txt
===================================================================
--- trunk/epydoc/doc/manual-docstring.txt 2007-02-21 17:34:54 UTC (rev 1547)
+++ trunk/epydoc/doc/manual-docstring.txt 2007-02-22 00:25:40 UTC (rev 1548)
@@ -1,66 +1,72 @@
-Docstrings and coding issues
-============================
+Python Docstrings
+=================
.. $Id$
-..
- This paragraph is introdictory: this chapter should explain advanced details.
+Python documentation strings (or *docstrings*) 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:
+.. python::
- Python docstrings
- -----------------
+ def x_intercept(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).
+ """
+ return -b/m
- Docstrings are a standard method that can be used by Python developers to
- attach documentation pieces to most Python objects.
+Docstrings can be accessed from the interpreter and from Python programs
+using the "``__doc__``" attribute:
- Here is an example module showing different docstrings:
+.. python::
- .. python::
+ >>> print x_intercept.__doc__
+ 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).
- #!/usr/bin/python
- # -*- coding: latin-1 -*-
- """A Sample Module.
+The pydoc_ module, which became part of `the standard library`__ in Python 2.1,
+can be used to display information about a Python object, including its
+docstring:
- The first string in the module, starting after the *hashbang* and the
- encoding definition comment, is the module docstring.
- """
+.. _pydoc: http://web.lfw.org/python/pydoc.html
+.. __: http://www.python.org/doc/current/lib/module-pydoc.html
- class Foo:
- """
- This is a testing class.
+.. python::
- It doesn't do much stuff, but it's pretty documented. This, for
- example, is the class docstring.
- """
+ >>> from pydoc import help
- def getMagic(self):
- """
- A function returning a magic number.
+ >>> help(x_intercept)
+ Help on function x_intercept in module __main__:
- This is the function documentation.
- """
- return 42
+ x_intercept(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).
- the_number = property(
- fget=getMagic,
- doc="""This is the property docstring.""")
+For more information about Python docstrings, see the `Python Tutorial`__ or
+the O'Reilly Network article `Python Documentation Tips and Tricks`__.
- Some guidelines for docstring standardization have been published, see for
- example :PEP:`257` for some higl-level convention. No docstring structure
- is enforced anyway by official documentation.
+.. __: http://www.python.org/doc/current/tut/node6.html#docstrings
+.. __: http://www.onlamp.com/lpt/a/python/2001/05/17/docstrings.html
Variable docstrings
-------------------
-Python variables don't support docstrings. The variable can be described in the
-module or class where it is defined using the tags ``@var``, ``@ivar``,
-``@cvar``; but this only allows for a textual description: no further metadata
-can be added to the variable (except for the type, using the ``@type`` tag).
+..
+ [xx] this should be somewhere else, i guess...
-Epydoc supports *variable docstrings*: 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
+Python don't support directly docstrings on variables: there is no attribute
+that can be attached to variables and retrieved interactively like the
+``__doc__`` attribute on modules, classes and functions.
+
+While the language doesn't directly provides for them, Epydoc supports
+*variable docstrings*: 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 (``__init__``) are considered instance variables:
.. python::
@@ -84,21 +90,8 @@
x = 22
x = 22 #: docstring for x
-A common Python idiom is to create instance variables settings their default
-value in the class instead of the constructor (hopefully if the default is
-immutable...). To avoid Epydoc to interpret such variable as a class variable,
-you can describe it using the tag ``@ivar`` in the context of a variable
-docstring:
-
-.. python::
-
- class B:
- y = 42
- """@ivar: This is an instance variable."""
-
Notice that variable docstrings are only available for documentation when the
source code is available for *parsing*: it is not possible to retrieve variable
-docstrings from introspection informations only.
Items visibility
Modified: trunk/epydoc/doc/manual-fields.txt
===================================================================
--- trunk/epydoc/doc/manual-fields.txt 2007-02-21 17:34:54 UTC (rev 1547)
+++ trunk/epydoc/doc/manual-fields.txt 2007-02-22 00:25:40 UTC (rev 1548)
@@ -1,4 +1,4 @@
-Epydoc fields
+Epydoc Fields
=============
.. $Id$
@@ -149,11 +149,26 @@
``@type`` *v*: ...
The type of the variable *v*.
-These tags are usually put in a module or class docstring. If fthe sources can
+These tags are usually put in a module or class docstring. If the sources can
be parsed by Epydoc it is also possible to document the variable in their own
docstrings: see `variable docstrings`_
+Epydoc considers class variables the ones defined directly defined in the
+class body. A common Python idiom is to create instance variables settings
+their default value in the class instead of the constructor (hopefully if the
+default is immutable...).
+If you want to force Epydoc to classify as instance variable one whose default
+value is set at class level, you can describe it using the tag ``@ivar`` in the
+context of a variable docstring:
+
+.. python::
+
+ class B:
+ y = 42
+ """@ivar: This is an instance variable."""
+
+
Properties parameters
'''''''''''''''''''''
Modified: trunk/epydoc/doc/manual.txt
===================================================================
--- trunk/epydoc/doc/manual.txt 2007-02-21 17:34:54 UTC (rev 1547)
+++ trunk/epydoc/doc/manual.txt 2007-02-22 00:25:40 UTC (rev 1548)
@@ -9,9 +9,7 @@
:Author: `Edward Loper <ed...@gr...>`__
-:Data: $Date$
-:Versione: 3.0b1
-:Revisione: $Revision$
+:Version: 3.0b1
:Abstract:
Epydoc is a tool for generating API documentation for Python modules,
@@ -40,8 +38,8 @@
.. include:: manual-install.txt
.. include:: manual-usage.txt
+.. include:: manual-docstring.txt
.. include:: manual-epytext.txt
.. include:: manual-fields.txt
.. include:: manual-othermarkup.txt
-.. include:: manual-docstring.txt
.. include:: manual-reference.txt
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|