[Python-checkins] python/nondist/peps pep-0256.txt,1.3,1.4 pep-0257.txt,1.5,1.6 pep-0258.txt,1.3,1.4 pep-0287.txt,1.3,1.4

[goodger@users.sourceforge.net]

Update of /cvsroot/python/python/nondist/peps
In directory usw-pr-cvs1:/tmp/cvs-serv30789

Modified Files:
	pep-0256.txt pep-0257.txt pep-0258.txt pep-0287.txt 
Log Message:
Converted to reStructuredText & updated.

Index: pep-0256.txt
===================================================================
RCS file: /cvsroot/python/python/nondist/peps/pep-0256.txt,v
retrieving revision 1.3
retrieving revision 1.4
diff -C2 -d -r1.3 -r1.4
*** pep-0256.txt	1 Aug 2002 22:32:33 -0000	1.3
--- pep-0256.txt	30 Aug 2002 03:10:51 -0000	1.4
***************
*** 3,10 ****
  Version: $Revision$
  Last-Modified: $Date$
! Author: goodger@users.sourceforge.net (David Goodger)
! Discussions-To: doc-sig@python.org
  Status: Draft
  Type: Standards Track
  Created: 01-Jun-2001
  Post-History: 13-Jun-2001
--- 3,11 ----
  Version: $Revision$
  Last-Modified: $Date$
! Author: David Goodger <goodger@users.sourceforge.net>
! Discussions-To: <doc-sig@python.org>
  Status: Draft
  Type: Standards Track
+ Content-Type: text/x-rst
  Created: 01-Jun-2001
  Post-History: 13-Jun-2001
***************
*** 12,291 ****
  
  Abstract
  
!     Python lends itself to inline documentation.  With its built-in
!     docstring syntax, a limited form of Literate Programming [1]_ is
!     easy to do in Python.  However, there are no satisfactory standard
!     tools for extracting and processing Python docstrings.  The lack
!     of a standard toolset is a significant gap in Python's
!     infrastructure; this PEP aims to fill the gap.
  
!     The issues surrounding docstring processing have been contentious
!     and difficult to resolve.  This PEP proposes a generic Docstring
!     Processing System (DPS) framework, which separates out the
!     components (program and conceptual), enabling the resolution of
!     individual issues either through consensus (one solution) or
!     through divergence (many).  It promotes standard interfaces which
!     will allow a variety of plug-in components (input context readers,
!     markup parsers, and output format writers) to be used.
  
!     The concepts of a DPS framework are presented independently of
!     implementation details.
  
  
  Roadmap to the Doctring PEPs
  
!     There are many aspects to docstring processing.  The "Docstring
!     PEPs" have broken up the issues in order to deal with each of them
!     in isolation, or as close as possible.  The individual aspects and
!     associated PEPs are as follows:
  
!     * Docstring syntax.  PEP 287, reStructuredText Docstring Format,
!       proposes a syntax for Python docstrings, PEPs, and other uses.
  
!     * Docstring semantics consist of at least two aspects:
  
!       - Conventions: the high-level structure of docstrings.  Dealt
!         with in PEP 257, Docstring Conventions.
  
!       - Methodology: rules for the informational content of
!         docstrings.  Not addressed.
  
!     * Processing mechanisms.  This PEP outlines the high-level issues
!       and specification of an abstract docstring processing system
!       (DPS).  PEP 258, Docutils Design Specification, is an overview
!       of the design and implementation of one DPS under development.
  
!     * Output styles: developers want the documentation generated from
!       their source code to look good, and there are many different
!       ideas about what that means.  PEP 258 touches on "Stylist
!       Transforms".  This aspect of docstring processing has yet to be
!       fully explored.
  
!     By separating out the issues, we can form consensus more easily
!     (smaller fights ;-), and accept divergence more readily.
  
  
  Rationale
  
!     There are standard inline documentation systems for some other
!     languages.  For example, Perl has POD [2]_ and Java has Javadoc
!     [3]_, but neither of these mesh with the Pythonic way.  POD syntax
!     is very explicit, but takes after Perl in terms of readability.
!     Javadoc is HTML-centric; except for '@field' tags, raw HTML is
!     used for markup.  There are also general tools such as Autoduck
!     [4]_ and Web (Tangle & Weave) [5]_, useful for multiple languages.
  
!     There have been many attempts to write auto-documentation systems
!     for Python (not an exhaustive list):
  
!     - Marc-Andre Lemburg's doc.py [6]_
  
!     - Daniel Larsson's pythondoc & gendoc [7]_
  
!     - Doug Hellmann's HappyDoc [8]_
  
!     - Laurence Tratt's Crystal [9]_
  
!     - Ka-Ping Yee's htmldoc & pydoc [10]_ (pydoc.py is now part of the
!       Python standard library; see below)
  
!     - Tony Ibbs' docutils [11]_
  
!     - Edward Loper's STminus formalization and related efforts [12]_
  
!     These systems, each with different goals, have had varying degrees
!     of success.  A problem with many of the above systems was
!     over-ambition combined with inflexibility.  They provided a
!     self-contained set of components: a docstring extraction system, a
!     markup parser, an internal processing system and one or more
!     output format writers with a fixed style.  Inevitably, one or more
!     aspects of each system had serious shortcomings, and they were not
!     easily extended or modified, preventing them from being adopted as
!     standard tools.
  
!     It has become clear (to this author, at least) that the "all or
!     nothing" approach cannot succeed, since no monolithic
!     self-contained system could possibly be agreed upon by all
!     interested parties.  A modular component approach designed for
!     extension, where components may be multiply implemented, may be
!     the only chance for success.  Standard inter-component APIs will
!     make the DPS components comprehensible without requiring detailed
!     knowledge of the whole, lowering the barrier for contributions,
!     and ultimately resulting in a rich and varied system.
  
!     Each of the components of a docstring processing system should be
!     developed independently.  A 'best of breed' system should be
!     chosen, either merged from existing systems, and/or developed
!     anew.  This system should be included in Python's standard
!     library.
  
  
  PyDoc & Other Existing Systems
  
!     PyDoc became part of the Python standard library as of release
!     2.1.  It extracts and displays docstrings from within the Python
!     interactive interpreter, from the shell command line, and from a
!     GUI window into a web browser (HTML).  Although a very useful
!     tool, PyDoc has several deficiencies, including:
  
!     - In the case of the GUI/HTML, except for some heuristic
!       hyperlinking of identifier names, no formatting of the
!       docstrings is done.  They are presented within <p><small><tt>
!       tags to avoid unwanted line wrapping.  Unfortunately, the result
!       is not attractive.
  
!     - PyDoc extracts docstrings and structural information (class
!       identifiers, method signatures, etc.) from imported module
!       objects.  There are security issues involved with importing
!       untrusted code.  Also, information from the source is lost when
!       importing, such as comments, "additional docstrings" (string
!       literals in non-docstring contexts; see PEP 258 [13]_), and the
!       order of definitions.
  
!     The functionality proposed in this PEP could be added to or used
!     by PyDoc when serving HTML pages.  The proposed docstring
!     processing system's functionality is much more than PyDoc needs in
!     its current form.  Either an independent tool will be developed
!     (which PyDoc may or may not use), or PyDoc could be expanded to
!     encompass this functionality and *become* the docstring processing
!     system (or one such system).  That decision is beyond the scope of
!     this PEP.
  
!     Similarly for other existing docstring processing systems, their
!     authors may or may not choose compatibility with this framework.
!     However, if this framework is accepted and adopted as the Python
!     standard, compatibility will become an important consideration in
!     these systems' future.
  
  
  Specification
  
!     The docstring processing system framework consists of components,
!     as follows::
  
!     1. Docstring conventions.  Documents issues such as:
  
!        - What should be documented where.
  
!        - First line is a one-line synopsis.
  
!        PEP 257, Docstring Conventions [14]_, documents some of these
!        issues.
  
!     2. Docstring processing system design specification.  Documents
!        issues such as:
  
!        - High-level spec: what a DPS does.
  
!        - Command-line interface for executable script.
  
!        - System Python API.
  
!        - Docstring extraction rules.
  
!        - Readers, which encapsulate the input context .
  
!        - Parsers.
  
!        - Document tree: the intermediate internal data structure.  The
!          output of the Parser and Reader, and the input to the Writer
!          all share the same data structure.
  
!        - Transforms, which modify the document tree.
  
!        - Writers for output formats.
  
!        - Distributors, which handle output management (one file, many
!          files, or objects in memory).
  
!        These issues are applicable to any docstring processing system
!        implementation.  PEP 258, Docutils Design Specification [13 ]_,
!        documents these issues.
  
!     3. Docstring processing system implementation.
  
!     4. Input markup specifications: docstring syntax.  PEP 287,
!        reStructuredText Docstring Format [15]_, proposes a standard
!        syntax.
  
!     5. Input parser implementations.
  
!     6. Input context readers ("modes": Python source code, PEP,
!        standalone text file, email, etc.) and implementations.
  
!     7. Stylists: certain input context readers may have associated
!        stylists which allow for a variety of output document styles.
  
!     8. Output formats (HTML, XML, TeX, DocBook, info, etc.) and writer
!        implementations.
  
!     Components 1, 2/3, and 4/5 are the subject of individual companion
!     PEPs.  If there is another implementation of the framework or
!     syntax/parser, additional PEPs may be required.  Multiple
!     implementations of each of components 6 and 7 will be required;
!     the PEP mechanism may be overkill for these components.
  
  
  Project Web Site
  
!     A SourceForge project has been set up for this work at
!     http://docutils.sourceforge.net/.
  
  
  References and Footnotes
  
!     [1] http://www.literateprogramming.com/
  
!     [2] Perl "Plain Old Documentation"
!         http://www.perldoc.com/perl5.6/pod/perlpod.html
  
!     [3] http://java.sun.com/j2se/javadoc/
  
!     [4] http://www.helpmaster.com/hlp-developmentaids-autoduck.htm
  
!     [5] http://www-cs-faculty.stanford.edu/~knuth/cweb.html
  
!     [6] http://www.lemburg.com/files/python/SoftwareDescriptions.html#doc.py
  
!     [7] http://starship.python.net/crew/danilo/pythondoc/
  
!     [8] http://happydoc.sourceforge.net/
  
!     [9] http://www.btinternet.com/~tratt/comp/python/crystal/
  
!     [10] http://www.python.org/doc/current/lib/module-pydoc.html
  
!     [11] http://homepage.ntlworld.com/tibsnjoan/docutils/
  
!     [12] http://www.cis.upenn.edu/~edloper/pydoc/
  
!     [13] PEP 258, Docutils Design Specification, Goodger
!          http://www.python.org/peps/pep-0258.html
  
!     [14] PEP 257, Docstring Conventions, Goodger, Van Rossum
!          http://www.python.org/peps/pep-0257.html
  
!     [15] PEP 287, reStructuredText Docstring Format, Goodger
!          http://www.python.org/peps/pep-0287.html
  
!     [16] http://www.python.org/sigs/doc-sig/
  
  
  Copyright
  
!     This document has been placed in the public domain.
  
  
  Acknowledgements
  
!     This document borrows ideas from the archives of the Python
!     Doc-SIG [16]_.  Thanks to all members past & present.
  
  
  
! Local Variables:
! mode: indented-text
! indent-tabs-mode: nil
! fill-column: 70
! sentence-end-double-space: t
! End:
--- 13,299 ----
  
  Abstract
+ ========
  
! Python lends itself to inline documentation.  With its built-in
! docstring syntax, a limited form of `Literate Programming`_ is easy to
! do in Python.  However, there are no satisfactory standard tools for
! extracting and processing Python docstrings.  The lack of a standard
! toolset is a significant gap in Python's infrastructure; this PEP aims
! to fill the gap.
  
! The issues surrounding docstring processing have been contentious and
! difficult to resolve.  This PEP proposes a generic Docstring
! Processing System (DPS) framework, which separates out the components
! (program and conceptual), enabling the resolution of individual issues
! either through consensus (one solution) or through divergence (many).
! It promotes standard interfaces which will allow a variety of plug-in
! components (input context readers, markup parsers, and output format
! writers) to be used.
  
! The concepts of a DPS framework are presented independently of
! implementation details.
  
  
  Roadmap to the Doctring PEPs
+ ============================
  
! There are many aspects to docstring processing.  The "Docstring PEPs"
! have broken up the issues in order to deal with each of them in
! isolation, or as close as possible.  The individual aspects and
! associated PEPs are as follows:
  
! * Docstring syntax.  PEP 287, "reStructuredText Docstring Format"
!   [#PEP-287]_, proposes a syntax for Python docstrings, PEPs, and
!   other uses.
  
! * Docstring semantics consist of at least two aspects:
  
!   - Conventions: the high-level structure of docstrings.  Dealt with
!     in PEP 257, "Docstring Conventions" [#PEP-257]_.
  
!   - Methodology: rules for the informational content of docstrings.
!     Not addressed.
  
! * Processing mechanisms.  This PEP (PEP 256) outlines the high-level
!   issues and specification of an abstract docstring processing system
!   (DPS).  PEP 258, "Docutils Design Specification" [#PEP-258]_, is an
!   overview of the design and implementation of one DPS under
!   development.
  
! * Output styles: developers want the documentation generated from
!   their source code to look good, and there are many different ideas
!   about what that means.  PEP 258 touches on "Stylist Transforms".
!   This aspect of docstring processing has yet to be fully explored.
  
! By separating out the issues, we can form consensus more easily
! (smaller fights ;-), and accept divergence more readily.
  
  
  Rationale
+ =========
  
! There are standard inline documentation systems for some other
! languages.  For example, Perl has POD_ ("Plain Old Documentation") and
! Java has Javadoc_, but neither of these mesh with the Pythonic way.
! POD syntax is very explicit, but takes after Perl in terms of
! readability.  Javadoc is HTML-centric; except for "``@field``" tags,
! raw HTML is used for markup.  There are also general tools such as
! Autoduck_ and Web_ (Tangle & Weave), useful for multiple languages.
  
! There have been many attempts to write auto-documentation systems
! for Python (not an exhaustive list):
  
! - Marc-Andre Lemburg's doc.py_
  
! - Daniel Larsson's pythondoc_ & gendoc_
  
! - Doug Hellmann's HappyDoc_
  
! - Laurence Tratt's Crystal_
  
! - Ka-Ping Yee's pydoc_ (pydoc.py is now part of the Python standard
!   library; see below)
  
! - Tony Ibbs' docutils_ (Tony has donated this name to the `Docutils
!   project`_)
  
! - Edward Loper's STminus_ formalization and related efforts
  
! These systems, each with different goals, have had varying degrees of
! success.  A problem with many of the above systems was over-ambition
! combined with inflexibility.  They provided a self-contained set of
! components: a docstring extraction system, a markup parser, an
! internal processing system and one or more output format writers with
! a fixed style.  Inevitably, one or more aspects of each system had
! serious shortcomings, and they were not easily extended or modified,
! preventing them from being adopted as standard tools.
  
! It has become clear (to this author, at least) that the "all or
! nothing" approach cannot succeed, since no monolithic self-contained
! system could possibly be agreed upon by all interested parties.  A
! modular component approach designed for extension, where components
! may be multiply implemented, may be the only chance for success.
! Standard inter-component APIs will make the DPS components
! comprehensible without requiring detailed knowledge of the whole,
! lowering the barrier for contributions, and ultimately resulting in a
! rich and varied system.
  
! Each of the components of a docstring processing system should be
! developed independently.  A "best of breed" system should be chosen,
! either merged from existing systems, and/or developed anew.  This
! system should be included in Python's standard library.
  
  
  PyDoc & Other Existing Systems
+ ------------------------------
  
! PyDoc became part of the Python standard library as of release 2.1.
! It extracts and displays docstrings from within the Python interactive
! interpreter, from the shell command line, and from a GUI window into a
! web browser (HTML).  Although a very useful tool, PyDoc has several
! deficiencies, including:
  
! - In the case of the GUI/HTML, except for some heuristic hyperlinking
!   of identifier names, no formatting of the docstrings is done.  They
!   are presented within ``<p><small><tt>`` tags to avoid unwanted line
!   wrapping.  Unfortunately, the result is not attractive.
  
! - PyDoc extracts docstrings and structural information (class
!   identifiers, method signatures, etc.) from imported module objects.
!   There are security issues involved with importing untrusted code.
!   Also, information from the source is lost when importing, such as
!   comments, "additional docstrings" (string literals in non-docstring
!   contexts; see PEP 258 [#PEP-258]_), and the order of definitions.
  
! The functionality proposed in this PEP could be added to or used by
! PyDoc when serving HTML pages.  The proposed docstring processing
! system's functionality is much more than PyDoc needs in its current
! form.  Either an independent tool will be developed (which PyDoc may
! or may not use), or PyDoc could be expanded to encompass this
! functionality and *become* the docstring processing system (or one
! such system).  That decision is beyond the scope of this PEP.
  
! Similarly for other existing docstring processing systems, their
! authors may or may not choose compatibility with this framework.
! However, if this framework is accepted and adopted as the Python
! standard, compatibility will become an important consideration in
! these systems' future.
  
  
  Specification
+ =============
  
! The docstring processing system framework is broken up as follows:
  
! 1. Docstring conventions.  Documents issues such as:
  
!    - What should be documented where.
  
!    - First line is a one-line synopsis.
  
!    PEP 257 [#PEP-257]_ documents some of these issues.
  
! 2. Docstring processing system design specification.  Documents
!    issues such as:
  
!    - High-level spec: what a DPS does.
  
!    - Command-line interface for executable script.
  
!    - System Python API.
  
!    - Docstring extraction rules.
  
!    - Readers, which encapsulate the input context .
  
!    - Parsers.
  
!    - Document tree: the intermediate internal data structure.  The
!      output of the Parser and Reader, and the input to the Writer all
!      share the same data structure.
  
!    - Transforms, which modify the document tree.
  
!    - Writers for output formats.
  
!    - Distributors, which handle output management (one file, many
!      files, or objects in memory).
  
!    These issues are applicable to any docstring processing system
!    implementation.  PEP 258 [#PEP-258]_ documents these issues.
  
! 3. Docstring processing system implementation.
  
! 4. Input markup specifications: docstring syntax.  PEP 287 [#PEP-287]_
!    proposes a standard syntax.
  
! 5. Input parser implementations.
  
! 6. Input context readers ("modes": Python source code, PEP, standalone
!    text file, email, etc.) and implementations.
  
! 7. Stylists: certain input context readers may have associated
!    stylists which allow for a variety of output document styles.
  
! 8. Output formats (HTML, XML, TeX, DocBook, info, etc.) and writer
!    implementations.
  
! Components 1, 2/3/5, and 4 are the subject of individual companion
! PEPs.  If there is another implementation of the framework or
! syntax/parser, additional PEPs may be required.  Multiple
! implementations of each of components 6 and 7 will be required; the
! PEP mechanism may be overkill for these components.
  
  
  Project Web Site
+ ================
  
! A SourceForge project has been set up for this work at
! http://docutils.sourceforge.net/.
  
  
  References and Footnotes
+ ========================
  
! .. [#PEP-287] PEP 287, reStructuredText Docstring Format, Goodger
!    (http://www.python.org/peps/pep-0287.html)
  
! .. [#PEP-257] PEP 257, Docstring Conventions, Goodger, Van Rossum
!    (http://www.python.org/peps/pep-0257.html)
  
! .. [#PEP-258] PEP 258, Docutils Design Specification, Goodger
!    (http://www.python.org/peps/pep-0258.html)
  
! .. _Literate Programming: http://www.literateprogramming.com/
  
! .. _POD: http://www.perldoc.com/perl5.6/pod/perlpod.html
  
! .. _Javadoc: http://java.sun.com/j2se/javadoc/
  
! .. _Autoduck:
!    http://www.helpmaster.com/hlp-developmentaids-autoduck.htm
  
! .. _Web: http://www-cs-faculty.stanford.edu/~knuth/cweb.html
  
! .. _doc.py:
!    http://www.lemburg.com/files/python/SoftwareDescriptions.html#doc.py
  
! .. _pythondoc:
! .. _gendoc: http://starship.python.net/crew/danilo/pythondoc/
  
! .. _HappyDoc: http://happydoc.sourceforge.net/
  
! .. _Crystal: http://www.btinternet.com/~tratt/comp/python/crystal/
  
! .. _pydoc: http://www.python.org/doc/current/lib/module-pydoc.html
  
! .. _docutils: http://homepage.ntlworld.com/tibsnjoan/docutils/
  
! .. _Docutils project: http://docutils.sourceforge.net/
  
! .. _STMinus: http://www.cis.upenn.edu/~edloper/pydoc/
! 
! .. _Python Doc-SIG: http://www.python.org/sigs/doc-sig/
  
  
  Copyright
+ =========
  
! This document has been placed in the public domain.
  
  
  Acknowledgements
+ ================
  
! This document borrows ideas from the archives of the `Python
! Doc-SIG`_.  Thanks to all members past & present.
  
  
  
! ..
!    Local Variables:
!    mode: indented-text
!    indent-tabs-mode: nil
!    sentence-end-double-space: t
!    fill-column: 70
!    End:

Index: pep-0257.txt
===================================================================
RCS file: /cvsroot/python/python/nondist/peps/pep-0257.txt,v
retrieving revision 1.5
retrieving revision 1.6
diff -C2 -d -r1.5 -r1.6
*** pep-0257.txt	1 Aug 2002 22:32:33 -0000	1.5
--- pep-0257.txt	30 Aug 2002 03:10:51 -0000	1.6
***************
*** 3,11 ****
  Version: $Revision$
  Last-Modified: $Date$
! Author: goodger@users.sourceforge.net (David Goodger),
!         guido@python.org (Guido van Rossum)
  Discussions-To: doc-sig@python.org
  Status: Active
  Type: Informational
  Created: 29-May-2001
  Post-History: 13-Jun-2001
--- 3,12 ----
  Version: $Revision$
  Last-Modified: $Date$
! Author: David Goodger <goodger@users.sourceforge.net>,
!         Guido van Rossum <guido@python.org>
  Discussions-To: doc-sig@python.org
  Status: Active
  Type: Informational
+ Content-Type: text/x-rst
  Created: 29-May-2001
  Post-History: 13-Jun-2001
***************
*** 13,256 ****
  
  Abstract
  
!     This PEP documents the semantics and conventions associated with
!     Python docstrings.
  
  
  Rationale
  
!     The aim of this PEP is to standardize the high-level structure of
!     docstrings: what they should contain, and how to say it (without
!     touching on any markup syntax within docstrings).  The PEP
!     contains conventions, not laws or syntax.
  
!         "A universal convention supplies all of maintainability,
!         clarity, consistency, and a foundation for good programming
!         habits too.  What it doesn't do is insist that you follow it
!         against your will.  That's Python!"
  
!         --Tim Peters on comp.lang.python, 2001-06-16
  
!     If you violate the conventions, the worst you'll get is some dirty
!     looks.  But some software (such as the Docutils docstring
!     processing system [1] [2]) will be aware of the conventions, so
!     following them will get you the best results.
  
  
  Specification
  
!     What is a Docstring?
!     --------------------
  
!     A docstring is a string literal that occurs as the first statement
!     in a module, function, class, or method definition.  Such a
!     docstring becomes the __doc__ special attribute of that object.
  
!     All modules should normally have docstrings, and all functions and
!     classes exported by a module should also have docstrings.  Public
!     methods (including the __init__ constructor) should also have
!     docstrings.  A package may be documented in the module docstring
!     of the __init__.py file in the package directory.
  
!     String literals occurring elsewhere in Python code may also act as
!     documentation.  They are not recognized by the Python bytecode
!     compiler and are not accessible as runtime object attributes
!     (i.e. not assigned to __doc__), but two types of extra docstrings
!     may be extracted by software tools:
  
!     1. String literals occurring immediately after a simple assignment
!        at the top level of a module, class, or __init__ method
!        are called "attribute docstrings".
  
!     2. String literals occurring immediately after another docstring
!        are called "additional docstrings".
  
!     Please see PEP 258 "Docutils Design Specification" [2] for a
!     detailed description of attribute and additional docstrings.
  
!     XXX Mention docstrings of 2.2 properties.
  
!     For consistency, always use """triple double quotes""" around
!     docstrings.  Use r"""raw triple double quotes""" if you use any
!     backslashes in your docstrings.  For Unicode docstrings, use
!     u"""Unicode triple-quoted strings""".
  
!     There are two forms of docstrings: one-liners and multi-line
!     docstrings.
  
-     One-line Docstrings
-     --------------------
  
!     One-liners are for really obvious cases.  They should really fit
!     on one line.  For example::
  
!         def kos_root():
!             """Return the pathname of the KOS root directory."""
!             global _kos_root
!             if _kos_root: return _kos_root
!             ...
  
!     Notes:
  
!     - Triple quotes are used even though the string fits on one line.
!       This makes it easy to later expand it.
  
!     - The closing quotes are on the same line as the opening quotes.
!       This looks better for one-liners.
  
!     - There's no blank line either before or after the docstring.
  
!     - The docstring is a phrase ending in a period.  It prescribes the
!       function or method's effect as a command ("Do this", "Return
!       that"), not as a description: e.g. don't write "Returns the
!       pathname ..."
  
!     - The one-line docstring should NOT be a "signature" reiterating
!       the function/method parameters (which can be obtained by
!       introspection).  Don't do::
  
!           def function(a, b):
!               """function(a, b) -> list"""
  
!       This type of docstring is only appropriate for C functions (such
!       as built-ins), where introspection is not possible.  However,
!       the nature of the *return value* cannot be determined by
!       introspection, so it should be mentioned.  The preferred form
!       for such a docstring would be something like::
  
!           def function(a, b):
!               """Do X and return a list."""
  
!       (Of course "Do X" should be replaced by a useful description!)
  
!     Multi-line Docstrings
!     ----------------------
  
-     Multi-line docstrings consist of a summary line just like a
-     one-line docstring, followed by a blank line, followed by a more
-     elaborate description.  The summary line may be used by automatic
-     indexing tools; it is important that it fits on one line and is
-     separated from the rest of the docstring by a blank line.  The
-     summary line may be on the same line as the opening quotes or on
-     the next line.
  
!     The entire docstring is indented the same as the quotes at its
!     first line (see example below).  Docstring processing tools will
!     strip an amount of indentation from the second and further lines
!     of the docstring equal to the indentation of the first non-blank
!     line after the first line of the docstring.  Relative indentation
!     of later lines in the docstring is retained.
  
!     Insert a blank line before and after all docstrings (one-line or
!     multi-line) that document a class -- generally speaking, the
!     class's methods are separated from each other by a single blank
!     line, and the docstring needs to be offset from the first method
!     by a blank line; for symmetry, put a blank line between the class
!     header and the docstring.  Docstrings documenting functions or
!     methods generally don't have this requirement, unless the function
!     or method's body is written as a number of blank-line separated
!     sections -- in this case, treat the docstring as another section,
!     and precede it with a blank line.
  
!     The docstring of a script (a stand-alone program) should be usable
!     as its "usage" message, printed when the script is invoked with
!     incorrect or missing arguments (or perhaps with a "-h" option, for
!     "help").  Such a docstring should document the script's function
!     and command line syntax, environment variables, and files.  Usage
!     messages can be fairly elaborate (several screens full) and should
!     be sufficient for a new user to use the command properly, as well
!     as a complete quick reference to all options and arguments for the
!     sophisticated user.
  
!     The docstring for a module should generally list the classes,
!     exceptions and functions (and any other objects) that are exported
!     by the module, with a one-line summary of each.  (These summaries
!     generally give less detail than the summary line in the object's
!     docstring.)  The docstring for a package (i.e., the docstring of
!     the package's __init__.py module) should also list the modules and
!     subpackages exported by the package.
  
!     The docstring for a function or method should summarize its
!     behavior and document its arguments, return value(s), side
!     effects, exceptions raised, and restrictions on when it can be
!     called (all if applicable).  Optional arguments should be
!     indicated.  It should be documented whether keyword arguments are
!     part of the interface.
  
!     The docstring for a class should summarize its behavior and list
!     the public methods and instance variables.  If the class is
!     intended to be subclassed, and has an additional interface for
!     subclasses, this interface should be listed separately (in the
!     docstring).  The class constructor should be documented in the
!     docstring for its __init__ method.  Individual methods should be
!     documented by their own docstring.
  
!     If a class subclasses another class and its behavior is mostly
!     inherited from that class, its docstring should mention this and
!     summarize the differences.  Use the verb "override" to indicate
!     that a subclass method replaces a superclass method and does not
!     call the superclass method; use the verb "extend" to indicate that
!     a subclass method calls the superclass method (in addition to its
!     own behavior).
  
!     *Do not* use the Emacs convention of mentioning the arguments of
!     functions or methods in upper case in running text.  Python is
!     case sensitive and the argument names can be used for keyword
!     arguments, so the docstring should document the correct argument
!     names.  It is best to list each argument on a separate line.  For
!     example::
  
!         def complex(real=0.0, imag=0.0):
!             """Form a complex number.
  
!             Keyword arguments:
!             real -- the real part (default 0.0)
!             imag -- the imaginary part (default 0.0)
  
!             """
!             if imag == 0.0 and real == 0.0: return complex_zero
!             ...
  
!     The BDFL [3] recommends inserting a blank line between the last
!     paragraph in a multi-line docstring and its closing quotes,
!     placing the closing quotes on a line by themselves.  This way,
!     Emacs' fill-paragraph command can be used on it.
  
  
  References and Footnotes
  
!     [1] PEP 256, Docstring Processing System Framework, Goodger
!         http://www.python.org/peps/pep-0256.html
  
!     [2] PEP 258, Docutils Design Specification, Goodger
!         http://www.python.org/peps/pep-0258.html
  
!     [3] Guido van Rossum, Python's creator and Benevolent Dictator For
!         Life.
  
!     [4] http://www.python.org/doc/essays/styleguide.html
  
!     [5] http://www.python.org/sigs/doc-sig/
  
  
  Copyright
  
!     This document has been placed in the public domain.
  
  
  Acknowledgements
  
!     The "Specification" text comes mostly verbatim from the Python
!     Style Guide essay by Guido van Rossum [4].
  
!     This document borrows ideas from the archives of the Python
!     Doc-SIG [5].  Thanks to all members past and present.
  
  
  
! Local Variables:
! mode: indented-text
! indent-tabs-mode: nil
! fill-column: 70
! sentence-end-double-space: t
! End:
--- 14,263 ----
  
  Abstract
+ ========
  
! This PEP documents the semantics and conventions associated with
! Python docstrings.
  
  
  Rationale
+ =========
  
! The aim of this PEP is to standardize the high-level structure of
! docstrings: what they should contain, and how to say it (without
! touching on any markup syntax within docstrings).  The PEP contains
! conventions, not laws or syntax.
  
!     "A universal convention supplies all of maintainability, clarity,
!     consistency, and a foundation for good programming habits too.
!     What it doesn't do is insist that you follow it against your will.
!     That's Python!"
  
!     -- Tim Peters on comp.lang.python, 2001-06-16
  
! If you violate these conventions, the worst you'll get is some dirty
! looks.  But some software (such as the Docutils_ docstring processing
! system [1]_ [2]_) will be aware of the conventions, so following them
! will get you the best results.
  
  
  Specification
+ =============
  
! What is a Docstring?
! --------------------
  
! A docstring is a string literal that occurs as the first statement in
! a module, function, class, or method definition.  Such a docstring
! becomes the ``__doc__`` special attribute of that object.
  
! All modules should normally have docstrings, and all functions and
! classes exported by a module should also have docstrings.  Public
! methods (including the ``__init__`` constructor) should also have
! docstrings.  A package may be documented in the module docstring of
! the ``__init__.py`` file in the package directory.
  
! String literals occurring elsewhere in Python code may also act as
! documentation.  They are not recognized by the Python bytecode
! compiler and are not accessible as runtime object attributes (i.e. not
! assigned to ``__doc__``), but two types of extra docstrings may be
! extracted by software tools:
  
! 1. String literals occurring immediately after a simple assignment at
!    the top level of a module, class, or ``__init__`` method are called
!    "attribute docstrings".
  
! 2. String literals occurring immediately after another docstring are
!    called "additional docstrings".
  
! Please see PEP 258, "Docutils Design Specification" [2]_, for a
! detailed description of attribute and additional docstrings.
  
! XXX Mention docstrings of 2.2 properties.
  
! For consistency, always use ``"""triple double quotes"""`` around
! docstrings.  Use ``r"""raw triple double quotes"""`` if you use any
! backslashes in your docstrings.  For Unicode docstrings, use
! ``u"""Unicode triple-quoted strings"""``.
  
! There are two forms of docstrings: one-liners and multi-line
! docstrings.
  
  
! One-line Docstrings
! --------------------
  
! One-liners are for really obvious cases.  They should really fit on
! one line.  For example::
  
!     def kos_root():
!         """Return the pathname of the KOS root directory."""
!         global _kos_root
!         if _kos_root: return _kos_root
!         ...
  
! Notes:
  
! - Triple quotes are used even though the string fits on one line.
!   This makes it easy to later expand it.
  
! - The closing quotes are on the same line as the opening quotes.  This
!   looks better for one-liners.
  
! - There's no blank line either before or after the docstring.
  
! - The docstring is a phrase ending in a period.  It prescribes the
!   function or method's effect as a command ("Do this", "Return that"),
!   not as a description; e.g. don't write "Returns the pathname ...".
  
! - The one-line docstring should NOT be a "signature" reiterating the
!   function/method parameters (which can be obtained by introspection).
!   Don't do::
  
!       def function(a, b):
!           """function(a, b) -> list"""
  
!   This type of docstring is only appropriate for C functions (such as
!   built-ins), where introspection is not possible.  However, the
!   nature of the *return value* cannot be determined by introspection,
!   so it should be mentioned.  The preferred form for such a docstring
!   would be something like::
  
!       def function(a, b):
!           """Do X and return a list."""
  
!   (Of course "Do X" should be replaced by a useful description!)
  
  
! Multi-line Docstrings
! ----------------------
  
! Multi-line docstrings consist of a summary line just like a one-line
! docstring, followed by a blank line, followed by a more elaborate
! description.  The summary line may be used by automatic indexing
! tools; it is important that it fits on one line and is separated from
! the rest of the docstring by a blank line.  The summary line may be on
! the same line as the opening quotes or on the next line.
  
! The entire docstring is indented the same as the quotes at its first
! line (see example below).  Docstring processing tools will strip an
! amount of indentation from the second and further lines of the
! docstring equal to the indentation of the first non-blank line after
! the first line of the docstring.  Relative indentation of later lines
! in the docstring is retained.
  
! Insert a blank line before and after all docstrings (one-line or
! multi-line) that document a class -- generally speaking, the class's
! methods are separated from each other by a single blank line, and the
! docstring needs to be offset from the first method by a blank line;
! for symmetry, put a blank line between the class header and the
! docstring.  Docstrings documenting functions or methods generally
! don't have this requirement, unless the function or method's body is
! written as a number of blank-line separated sections -- in this case,
! treat the docstring as another section, and precede it with a blank
! line.
  
! The docstring of a script (a stand-alone program) should be usable as
! its "usage" message, printed when the script is invoked with incorrect
! or missing arguments (or perhaps with a "-h" option, for "help").
! Such a docstring should document the script's function and command
! line syntax, environment variables, and files.  Usage messages can be
! fairly elaborate (several screens full) and should be sufficient for a
! new user to use the command properly, as well as a complete quick
! reference to all options and arguments for the sophisticated user.
  
! The docstring for a module should generally list the classes,
! exceptions and functions (and any other objects) that are exported by
! the module, with a one-line summary of each.  (These summaries
! generally give less detail than the summary line in the object's
! docstring.)  The docstring for a package (i.e., the docstring of the
! package's ``__init__.py`` module) should also list the modules and
! subpackages exported by the package.
  
! The docstring for a function or method should summarize its behavior
! and document its arguments, return value(s), side effects, exceptions
! raised, and restrictions on when it can be called (all if applicable).
! Optional arguments should be indicated.  It should be documented
! whether keyword arguments are part of the interface.
  
! The docstring for a class should summarize its behavior and list the
! public methods and instance variables.  If the class is intended to be
! subclassed, and has an additional interface for subclasses, this
! interface should be listed separately (in the docstring).  The class
! constructor should be documented in the docstring for its ``__init__``
! method.  Individual methods should be documented by their own
! docstring.
  
! If a class subclasses another class and its behavior is mostly
! inherited from that class, its docstring should mention this and
! summarize the differences.  Use the verb "override" to indicate that a
! subclass method replaces a superclass method and does not call the
! superclass method; use the verb "extend" to indicate that a subclass
! method calls the superclass method (in addition to its own behavior).
  
! *Do not* use the Emacs convention of mentioning the arguments of
! functions or methods in upper case in running text.  Python is case
! sensitive and the argument names can be used for keyword arguments, so
! the docstring should document the correct argument names.  It is best
! to list each argument on a separate line.  For example::
  
!     def complex(real=0.0, imag=0.0):
!         """Form a complex number.
  
!         Keyword arguments:
!         real -- the real part (default 0.0)
!         imag -- the imaginary part (default 0.0)
! 
!         """
!         if imag == 0.0 and real == 0.0: return complex_zero
!         ...
! 
! The BDFL [3]_ recommends inserting a blank line between the last
! paragraph in a multi-line docstring and its closing quotes, placing
! the closing quotes on a line by themselves.  This way, Emacs'
! ``fill-paragraph`` command can be used on it.
  
  
  References and Footnotes
+ ========================
  
! .. [1] PEP 256, Docstring Processing System Framework, Goodger
!    (http://www.python.org/peps/pep-0256.html)
  
! .. [2] PEP 258, Docutils Design Specification, Goodger
!    (http://www.python.org/peps/pep-0258.html)
  
! .. [3] Guido van Rossum, Python's creator and Benevolent Dictator For
!    Life.
  
! .. _Docutils: http://docutils.sourceforge.net/
  
! .. _Python Style Guide:
!    http://www.python.org/doc/essays/styleguide.html
! 
! .. _Doc-SIG: http://www.python.org/sigs/doc-sig/
  
  
  Copyright
+ =========
  
! This document has been placed in the public domain.
  
  
  Acknowledgements
+ ================
  
! The "Specification" text comes mostly verbatim from the `Python Style
! Guide`_ essay by Guido van Rossum.
  
! This document borrows ideas from the archives of the Python Doc-SIG_.
! Thanks to all members past and present.
  
  
  
! ..
!    Local Variables:
!    mode: indented-text
!    indent-tabs-mode: nil
!    fill-column: 70
!    sentence-end-double-space: t
!    End:

Index: pep-0258.txt
===================================================================
RCS file: /cvsroot/python/python/nondist/peps/pep-0258.txt,v
retrieving revision 1.3
retrieving revision 1.4
diff -C2 -d -r1.3 -r1.4
*** pep-0258.txt	1 Aug 2002 22:32:33 -0000	1.3
--- pep-0258.txt	30 Aug 2002 03:10:51 -0000	1.4
***************
*** 3,10 ****
  Version: $Revision$
  Last-Modified: $Date$
! Author: goodger@users.sourceforge.net (David Goodger)
! Discussions-To: doc-sig@python.org
  Status: Draft
  Type: Standards Track
  Requires: 256, 257
  Created: 31-May-2001
--- 3,11 ----
  Version: $Revision$
[...1821 lines suppressed...]
  
! This document has been placed in the public domain.
  
  
! ==================
!  Acknowledgements
! ==================
  
! This document borrows ideas from the archives of the `Python
! Doc-SIG`_.  Thanks to all members past & present.
  
  
  
! ..
!    Local Variables:
!    mode: indented-text
!    indent-tabs-mode: nil
!    sentence-end-double-space: t
!    fill-column: 70
!    End:

Index: pep-0287.txt
===================================================================
RCS file: /cvsroot/python/python/nondist/peps/pep-0287.txt,v
retrieving revision 1.3
retrieving revision 1.4
diff -C2 -d -r1.3 -r1.4
*** pep-0287.txt	1 Aug 2002 22:32:33 -0000	1.3
--- pep-0287.txt	30 Aug 2002 03:10:51 -0000	1.4
***************
*** 3,10 ****
  Version: $Revision$
  Last-Modified: $Date$
! Author: goodger@users.sourceforge.net (David Goodger)
! Discussions-To: doc-sig@python.org
  Status: Draft
  Type: Informational
  Created: 25-Mar-2002
  Post-History: 02-Apr-2002
--- 3,11 ----
  Version: $Revision$
[...1594 lines suppressed...]
! This document has been placed in the public domain.
  
  
  Acknowledgements
+ ================
  
! Some text is borrowed from PEP 216, Docstring Format [#PEP-216]_, by
! Moshe Zadka.
  
! Special thanks to all members past & present of the Python Doc-SIG_.
  
  
  
! ..
!    Local Variables:
!    mode: indented-text
!    indent-tabs-mode: nil
!    sentence-end-double-space: t
!    fill-column: 70
!    End: