|Last-Modified:||2007-07-23 05:20:49 +0000 (Mon, 23 Jul 2007)|
|Author:||Marc-André Lemburg <mal at lemburg.com>|
This PEP describes the "attribute docstring" proposal for Python 2.0. This PEP tracks the status and ownership of this feature. It contains a description of the feature and outlines changes necessary to support the feature. The CVS revision history of this file contains the definitive historical record.
This PEP proposes a small addition to the way Python currently handles docstrings embedded in Python code. Python currently only handles the case of docstrings which appear directly after a class definition, a function definition or as first string literal in a module. The string literals are added to the objects in question under the __doc__ attribute and are from then on available for introspection tools which can extract the contained information for help, debugging and documentation purposes. Docstrings appearing in locations other than the ones mentioned are simply ignored and don't result in any code generation. Here is an example: class C: "class C doc-string" a = 1 "attribute C.a doc-string (1)" b = 2 "attribute C.b doc-string (2)" The docstrings (1) and (2) are currently being ignored by the Python byte code compiler, but could obviously be put to good use for documenting the named assignments that precede them. This PEP proposes to also make use of these cases by proposing semantics for adding their content t