Added PEP 224, Attribute Docstrings, assigned to MAL.

pep-0000.txt

@@ -48,6 +48,7 @@ Index
  SA  221  pep-0221.txt  Import As                              Wouters
  SD  222  pep-0222.txt  Web Library Enhancements               Kuchling
  S   223  pep-0223.txt  Change the Meaning of \x Escapes       Peters
+ S   224  pep-0224.txt  Attribute Docstrings                   Lemburg
 
 
 Key
@@ -67,6 +68,7 @@ Owners
     Drake, Fred              fdrake@beopen.com
     Hylton, Jeremy           jeremy@beopen.com
     Kuchling, Andrew         akuchlin@mems-exchange.org
+    Lemburg, Marc-Andre      mal@lemburg.com
     McMillan, Gordon         gmcm@hypernet.com
     Peters, Tim              tpeters@beopen.com
     Prescod, Paul            paul@prescod.net

pep-0224.txt

@@ -0,0 +1,150 @@
+PEP: 224
+Title: Attribute Docstrings
+Version: $Revision$
+Author: mal@lemburg.com (Marc-Andre Lemburg)
+Status: Draft
+Type: Standards Track
+Python-Version: 2.0
+Created: 23-Aug-2000
+Post-History:
+
+
+Introduction
+
+    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.
+
+
+Rationale
+
+    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 to the objects in which they
+    appear under new generated attribute names.
+
+    The original idea behind this approach which also inspired the
+    above example was to enable inline documentation of class
+    attributes, which can currently only be documented in the class's
+    docstring or using comments which are not available for
+    introspection.
+
+
+Implementation
+
+    Docstrings are handled by the byte code compiler as expressions.
+    The current implementation special cases the few locations
+    mentioned above to make use of these expressions, but otherwise
+    ignores the strings completely.
+
+    To enable use of these docstrings for documenting named
+    assignments (which is the natural way of defining e.g. class
+    attributes), the compiler will have to keep track of the last
+    assigned name and then use this name to assign the content of the
+    docstring to an attribute of the containing object by means of
+    storing it in as a constant which is then added to the object's
+    namespace during object construction time.
+
+    In order to preserve features like inheritance and hiding of
+    Python's special attributes (ones with leading and trailing double
+    underscores), a special name mangling has to be applied which
+    uniquely identifies the docstring as belonging to the name
+    assignment and allows finding the docstring later on by inspecting
+    the namespace.
+
+    The following name mangling scheme achieves all of the above:
+
+        __doc__<attributename>__
+
+    To keep track of the last assigned name, the byte code compiler
+    stores this name in a variable of the compiling structure.  This
+    variable defaults to NULL.  When it sees a docstring, it then
+    checks the variable and uses the name as basis for the above name
+    mangling to produce an implicit assignment of the docstring to the
+    mangled name.  It then resets the variable to NULL to avoid
+    duplicate assignments.
+
+    If the variable does not point to a name (i.e. is NULL), no
+    assignments are made.  These will continue to be ignored like
+    before.  All classical docstrings fall under this case, so no
+    duplicate assignments are done.
+
+    In the above example this would result in the following new class
+    attributes to be created:
+
+        C.__doc__a__ == "attribute C.a doc-string (1)"
+        C.__doc__b__ == "attribute C.b doc-string (2)"
+
+
+Caveats of the Implementation
+    
+    Since the implementation does not reset the compiling structure
+    variable when processing a non-expression, e.g. a function
+    definition, the last assigned name remains active until either the
+    next assignment or the next occurrence of a docstring.
+
+    This can lead to cases where the docstring and assignment may be
+    separated by other expressions:
+
+        class C:
+            "C doc string"
+
+            b = 2
+
+            def x(self):
+                "C.x doc string"
+                y = 3
+                return 1
+
+            "b's doc string"
+
+    Since the definition of method "x" currently does not reset the
+    used assignment name variable, it is still valid when the compiler
+    reaches [TBD: please finish your thought!]
+
+    
+Copyright
+
+    This document has been placed in the Public Domain.
+
+
+References
+
+    [1] http://sourceforge.net/patch/?func=detailpatch&patch_id=XXX&group_id=5470
+
+
+
+Local Variables:
+mode: indented-text
+indent-tabs-mode: nil
+End: