[Docstring-checkins] CVS: dps/spec python-docstring-mode.txt,NONE,1.1

[David G. <go...@us...>]

Update of /cvsroot/docstring/dps/spec
In directory usw-pr-cvs1:/tmp/cvs-serv4864/dps/spec

Added Files:
	python-docstring-mode.txt 
Log Message:
*** empty log message ***

--- NEW FILE: python-docstring-mode.txt ---
=======================
 Python Docstring Mode
=======================
:Author: David Goodger
:Contact: go...@us...
:Revision: $Revision: 1.1 $
:Date: $Date: 2001/09/05 02:33:58 $

This document details Python-specific interpretations of the
`reStructuredText Markup Specification`_, part of the
reStructuredText_ project, in the context of the `Python Docstring
Processing System`_.

For definitive element hierarchy details, see the "Python Plaintext
Document Interface DTD" XML document type definition, ppdi.dtd_ (which
modifies the generic gpdi.dtd_). Descriptions below list 'DTD
elements' (XML 'generic identifiers' or tag names) corresponding to
syntax constructs.


Interpreted Text
================

DTD elements: package, module, class, method, function,
module_attribute, class_attribute, instance_attribute, variable,
parameter, type, exception_class, warning_class.

In Python docstrings, interpreted text is used to classify and mark up
program identifiers, such as the names of variables, functions,
classes, and modules. If the identifier alone is given, its role is
inferred implicitly according to the Python namespace lookup rules.
For functions and methods (even when dynamically assigned),
parentheses ('()') may be included::

    This function uses `another()` to do its work.

For class, instance and module attributes, dotted identifiers are used
when necessary::

    class Keeper(Storer):

        """
        Extend `Storer`. Class attribute `instances` keeps track of
        the number of `Keeper` objects instantiated.
        """

        instances = 0
        """How many `Keeper` objects are there?"""

        def __init__(self):
            """
            Extend `Storer.__init__()` to keep track of instances.

            Keep count in `self.instances` and data in `self.data`.
            """
            Storer.__init__(self)
            self.instances += 1

            self.data = []
            """Store data in a list, most recent last."""

        def storedata(self, data):
            """
            Extend `Storer.storedata()`; append new `data` to a list
            (in `self.data`).
            """
            self.data = data

To classify identifiers explicitly, the role is given along with the
identifier in either prefix or suffix form::

    Use method:`Keeper.storedata` to store the object's data in the
    `Keeper.data`:instance_attribute.

The role may be one of 'package', 'module', 'class', 'method',
'function', 'module_attribute', 'class_attribute',
'instance_attribute', 'variable', 'parameter', 'type',
'exception_class', 'exception', 'warning_class', or 'warning'. Other
roles may be defined.

.. _reStructuredText Markup Specification:
    http://structuredtext.sourceforge.net/spec/reStructuredText.txt
.. _reStructuredText: http://structuredtext.sourceforge.net
.. _Python Docstring Processing System:
    http://docstring.sourceforge.net
.. _ppdi.dtd: http://docstring.sourceforge.net/spec/ppdi.dtd
.. _gpdi.dtd: http://docstring.sourceforge.net/spec/gpdi.dtd


Local Variables:
mode: indented-text
indent-tabs-mode: nil
fill-column: 70
End: