[Epydoc-commits] SF.net SVN: epydoc: [1395] branches/exp-args_in_class/epydoc/src/epydoc

[<dva...@us...>]

Revision: 1395
          http://svn.sourceforge.net/epydoc/?rev=1395&view=rev
Author:   dvarrazzo
Date:     2006-09-16 05:57:14 -0700 (Sat, 16 Sep 2006)

Log Message:
-----------
- Class docstring fields are passed to __init__ without using an extra ClassDoc
  attribute.
- Some docstring fixed.

Modified Paths:
--------------
    branches/exp-args_in_class/epydoc/src/epydoc/apidoc.py
    branches/exp-args_in_class/epydoc/src/epydoc/docstringparser.py

Modified: branches/exp-args_in_class/epydoc/src/epydoc/apidoc.py
===================================================================
--- branches/exp-args_in_class/epydoc/src/epydoc/apidoc.py	2006-09-16 00:20:06 UTC (rev 1394)
+++ branches/exp-args_in_class/epydoc/src/epydoc/apidoc.py	2006-09-16 12:57:14 UTC (rev 1395)
@@ -1118,10 +1118,6 @@
     """@ivar: API documentation for the class's known subclasses.
     @type: C{list} of L{ClassDoc}"""
     #}
-    init_args = UNKNOWN
-    """@ivar: Tags to be used as constructor documentation.
-    @type: C{list} of C{(tag, arg, descr)} tuples"""
-    #}
 
     def apidoc_links(self, **filters):
         val_docs = NamespaceDoc.apidoc_links(self, **filters)

Modified: branches/exp-args_in_class/epydoc/src/epydoc/docstringparser.py
===================================================================
--- branches/exp-args_in_class/epydoc/src/epydoc/docstringparser.py	2006-09-16 00:20:06 UTC (rev 1394)
+++ branches/exp-args_in_class/epydoc/src/epydoc/docstringparser.py	2006-09-16 12:57:14 UTC (rev 1395)
@@ -168,18 +168,16 @@
         user docfields defined by containing objects.
     """
     if api_doc.metadata is not UNKNOWN:
-        log.debug("%s's docstring processed twice" % api_doc.canonical_name)
+        if not (isinstance(api_doc, RoutineDoc)
+                and api_doc.canonical_name[-1] == '__init__'):
+            log.debug("%s's docstring processed twice" % api_doc.canonical_name)
         return
         
     initialize_api_doc(api_doc)
 
     # If there's no docstring, then there's nothing more to do.
-    # ...except in a case: an __init__ function that is to receive some
-    # documentation from the class docstring
     if (api_doc.docstring in (None, UNKNOWN)):
-        if not (isinstance(api_doc, RoutineDoc)
-                and api_doc.canonical_name[-1] == '__init__'):
-            return
+        return
 
     # Remove leading indentation from the docstring.
     api_doc.docstring = unindent_docstring(api_doc.docstring)
@@ -188,10 +186,6 @@
     # overrides any signature we got via introspection/parsing.
     if isinstance(api_doc, RoutineDoc):
         parse_function_signature(api_doc)
-    elif isinstance(api_doc, ClassDoc):
-        initvar = api_doc.variables.get('__init__')
-        if initvar:
-            parse_function_signature(initvar.value, api_doc)
 
     # Parse the docstring.  Any errors encountered are stored as
     # `ParseError` objects in the errors list.
@@ -211,14 +205,23 @@
     # docstring. This code assumes that a class docstring is parsed before
     # the same class __init__ docstring.
     if isinstance(api_doc, ClassDoc):
-        split_init_fields(fields, api_doc.init_args, field_warnings)
 
-    elif (isinstance(api_doc, RoutineDoc)
-          and api_doc.canonical_name[-1] == '__init__'):
-        class_doc = docindex.get_valdoc(api_doc.canonical_name[:-1])
-        if class_doc is not None and class_doc.init_args is not UNKNOWN:
-            fields.extend(class_doc.init_args)
+        # Parse ahead the __init__ docstring for this class
+        initvar = api_doc.variables.get('__init__')
+        if initvar and initvar.value not in (None, UNKNOWN):
+            init_api_doc = initvar.value
+            parse_docstring(init_api_doc, docindex)
 
+            parse_function_signature(init_api_doc, api_doc)
+            init_fields = split_init_fields(fields, field_warnings)
+
+            # Process fields
+            for field in init_fields:
+                try:
+                    process_field(init_api_doc, docindex, field.tag(),
+                                    field.arg(), field.body())
+                except ValueError, e: field_warnings.append(str(e))
+
     # Process fields
     for field in fields:
         try:
@@ -255,9 +258,6 @@
         api_doc.summary = None
     if api_doc.metadata is UNKNOWN:
         api_doc.metadata = []
-    if isinstance(api_doc, ClassDoc):
-        if api_doc.init_args is UNKNOWN:
-            api_doc.init_args = []
     if isinstance(api_doc, RoutineDoc):
         if api_doc.arg_descrs is UNKNOWN:
             api_doc.arg_descrs = []
@@ -278,13 +278,20 @@
         if api_doc.sort_spec is UNKNOWN:
             api_doc.sort_spec = []
 
-def split_init_fields(fields, init_fields, warnings):
+def split_init_fields(fields, warnings):
     """
-    Move the fields related to init into a different list.
-    C{fields} is supposed obtained from a class docstring. Remove
-    fields not related to the class from it and add them to C{init_fields},
-    which is a list of constructor fields.
+    Remove the fields related to the constructor from a class docstring
+    fields list.
+
+    @param fields: The fields to process. The list will be modified in place
+    @type fields: C{list} of L{markup.Field}
+    @param warnings: A list to emit processing warnings
+    @type warnings: C{list}
+    @return: The C{fields} items to be applied to the C{__init__} method
+    @rtype: C{list} of L{markup.Field}
     """
+    init_fields = []
+
     # Split fields in lists according to their argument, keeping order.
     arg_fields = {}
     args_order = []
@@ -354,6 +361,8 @@
             else:
                 pass # [xx] warn about type w/o object?
 
+    return init_fields
+
 def report_errors(api_doc, docindex, parse_errors, field_warnings):
     """A helper function for L{parse_docstring()} that reports any
     markup warnings and field warnings that we encountered while
@@ -902,10 +911,10 @@
 
     @param func_doc: The target object where to store parsed signature. Also
         container of the docstring to parse if doc_source is C{None}
-    @type L{RoutineDoc}
+    @type func_doc: L{RoutineDoc}
     @param doc_source: Contains the docstring to parse. If C{None}, parse
         L{func_doc} docstring instead
-    @type L{APIDoc}
+    @type doc_source: L{APIDoc}
     @rtype: C{None}
     """
     if doc_source is None:


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.