[Python-checkins] r62554 - python/trunk/Doc/library/pyclbr.rst

[skip.montanaro]

Author: skip.montanaro
Date: Mon Apr 28 04:59:45 2008
New Revision: 62554

Log:
Correct documentation to match implementation: "Class" instead of
"class_descriptor", "Function" instead of "function_descriptor".  Note
default path value for readmodule*.  Wrap some long paragraphs.  Don't
mention 'inpackage' which isn't part of the public API.



Modified:
   python/trunk/Doc/library/pyclbr.rst

Modified: python/trunk/Doc/library/pyclbr.rst
==============================================================================
--- python/trunk/Doc/library/pyclbr.rst	(original)
+++ python/trunk/Doc/library/pyclbr.rst	Mon Apr 28 04:59:45 2008
@@ -7,75 +7,75 @@
 .. sectionauthor:: Fred L. Drake, Jr. <fdrake at acm.org>
 
 
-The :mod:`pyclbr` can be used to determine some limited information about the
-classes, methods and top-level functions defined in a module.  The information
-provided is sufficient to implement a traditional three-pane class browser.  The
-information is extracted from the source code rather than by importing the
-module, so this module is safe to use with untrusted source code.  This
-restriction makes it impossible to use this module with modules not implemented
-in Python, including many standard and optional extension modules.
-
-
-.. function:: readmodule(module[, path])
-
-   Read a module and return a dictionary mapping class names to class descriptor
-   objects.  The parameter *module* should be the name of a module as a string;
-   it may be the name of a module within a package.  The *path* parameter should
-   be a sequence, and is used to augment the value of ``sys.path``, which is
-   used to locate module source code.
-
-   .. The 'inpackage' parameter appears to be for internal use only....
-
-
-.. function:: readmodule_ex(module[, path])
-
-   Like :func:`readmodule`, but the returned dictionary, in addition to mapping
-   class names to class descriptor objects, also maps top-level function names to
-   function descriptor objects.  Moreover, if the module being read is a package,
-   the key ``'__path__'`` in the returned dictionary has as its value a list which
-   contains the package search path.
-
-   .. The 'inpackage' parameter appears to be for internal use only....
+The :mod:`pyclbr` module can be used to determine some limited information
+about the classes, methods and top-level functions defined in a module.  The
+information provided is sufficient to implement a traditional three-pane
+class browser.  The information is extracted from the source code rather
+than by importing the module, so this module is safe to use with untrusted
+code.  This restriction makes it impossible to use this module with modules
+not implemented in Python, including all standard and optional extension
+modules.
+
+
+.. function:: readmodule(module[, path=None])
+
+   Read a module and return a dictionary mapping class names to class
+   descriptor objects.  The parameter *module* should be the name of a
+   module as a string; it may be the name of a module within a package.  The
+   *path* parameter should be a sequence, and is used to augment the value
+   of ``sys.path``, which is used to locate module source code.
+
+
+.. function:: readmodule_ex(module[, path=None])
+
+   Like :func:`readmodule`, but the returned dictionary, in addition to
+   mapping class names to class descriptor objects, also maps top-level
+   function names to function descriptor objects.  Moreover, if the module
+   being read is a package, the key ``'__path__'`` in the returned
+   dictionary has as its value a list which contains the package search
+   path.
 
 
 .. _pyclbr-class-objects:
 
-Class Descriptor Objects
-------------------------
+Class Objects
+-------------
 
-The class descriptor objects used as values in the dictionary returned by
-:func:`readmodule` and :func:`readmodule_ex` provide the following data members:
+The :class:`Class` objects used as values in the dictionary returned by
+:func:`readmodule` and :func:`readmodule_ex` provide the following data
+members:
 
 
-.. attribute:: class_descriptor.module
+.. attribute:: Class.module
 
    The name of the module defining the class described by the class descriptor.
 
 
-.. attribute:: class_descriptor.name
+.. attribute:: Class.name
 
    The name of the class.
 
 
-.. attribute:: class_descriptor.super
+.. attribute:: Class.super
 
-   A list of class descriptors which describe the immediate base classes of the
-   class being described.  Classes which are named as superclasses but which are
-   not discoverable by :func:`readmodule` are listed as a string with the class
-   name instead of class descriptors.
+   A list of :class:`Class` objects which describe the immediate base
+   classes of the class being described.  Classes which are named as
+   superclasses but which are not discoverable by :func:`readmodule` are
+   listed as a string with the class name instead of as :class:`Class`
+   objects.
 
 
-.. attribute:: class_descriptor.methods
+.. attribute:: Class.methods
 
    A dictionary mapping method names to line numbers.
 
 
-.. attribute:: class_descriptor.file
+.. attribute:: Class.file
 
    Name of the file containing the ``class`` statement defining the class.
 
 
-.. attribute:: class_descriptor.lineno
+.. attribute:: Class.lineno
 
    The line number of the ``class`` statement within the file named by
    :attr:`file`.
@@ -83,30 +83,31 @@
 
 .. _pyclbr-function-objects:
 
-Function Descriptor Objects
----------------------------
+Function Objects
+----------------
 
-The function descriptor objects used as values in the dictionary returned by
+The :class:`Function` objects used as values in the dictionary returned by
 :func:`readmodule_ex` provide the following data members:
 
 
-.. attribute:: function_descriptor.module
+.. attribute:: Function.module
 
    The name of the module defining the function described by the function
    descriptor.
 
 
-.. attribute:: function_descriptor.name
+.. attribute:: Function.name
 
    The name of the function.
 
 
-.. attribute:: function_descriptor.file
+.. attribute:: Function.file
 
    Name of the file containing the ``def`` statement defining the function.
 
 
-.. attribute:: function_descriptor.lineno
+.. attribute:: Function.lineno
 
-   The line number of the ``def`` statement within the file named by :attr:`file`.
+   The line number of the ``def`` statement within the file named by
+   :attr:`file`.