[Epydoc-commits] SF.net SVN: epydoc: [1358] trunk/epydoc/src/epydoc

[<ed...@us...>]

Revision: 1358
          http://svn.sourceforge.net/epydoc/?rev=1358&view=rev
Author:   edloper
Date:     2006-09-06 13:06:18 -0700 (Wed, 06 Sep 2006)

Log Message:
-----------
- If the summary is empty, but the return field is not, then generate
  a summary from 'Return'+return_descr
- Fixed bug in details display w/ empty descr
- split_fields() now returns None for the body if the body is empty
  (i.e., the dosctring contained only fields)

Modified Paths:
--------------
    trunk/epydoc/src/epydoc/docstringparser.py
    trunk/epydoc/src/epydoc/docwriter/html.py
    trunk/epydoc/src/epydoc/docwriter/html_css.py
    trunk/epydoc/src/epydoc/markup/__init__.py
    trunk/epydoc/src/epydoc/markup/epytext.py
    trunk/epydoc/src/epydoc/markup/javadoc.py
    trunk/epydoc/src/epydoc/markup/restructuredtext.py

Modified: trunk/epydoc/src/epydoc/docstringparser.py
===================================================================
--- trunk/epydoc/src/epydoc/docstringparser.py	2006-09-06 19:29:30 UTC (rev 1357)
+++ trunk/epydoc/src/epydoc/docstringparser.py	2006-09-06 20:06:18 UTC (rev 1358)
@@ -205,13 +205,16 @@
                                field.arg(), field.body())
         except ValueError, e: field_warnings.append(str(e))
 
-    # [XX] If descr is empty but we have a return field, 
-    # generate a descr from it..
-
     # Extract a summary
     if api_doc.summary is None and api_doc.descr is not None:
         api_doc.summary = api_doc.descr.summary()
 
+    # If the summary is empty, but the return field is not, then use
+    # the return field to generate a summary description.
+    if (isinstance(api_doc, RoutineDoc) and api_doc.summary is None and
+        api_doc.return_descr is not None):
+        api_doc.summary = RETURN_PDS + api_doc.return_descr.summary()
+
     # [XX] Make sure we don't have types/param descrs for unknown
     # vars/params?
 
@@ -321,6 +324,11 @@
     # End the message block.
     log.end_block()
 
+RETURN_PDS = markup.parse('Returns', markup='epytext')
+"""A ParsedDocstring containing the text 'Returns'.  This is used to
+construct summary descriptions for routines that have empty C{descr},
+but non-empty C{return_descr}."""
+
 ######################################################################
 #{ Field Processing Error Messages
 ######################################################################

Modified: trunk/epydoc/src/epydoc/docwriter/html.py
===================================================================
--- trunk/epydoc/src/epydoc/docwriter/html.py	2006-09-06 19:29:30 UTC (rev 1357)
+++ trunk/epydoc/src/epydoc/docwriter/html.py	2006-09-06 20:06:18 UTC (rev 1358)
@@ -1974,6 +1974,8 @@
 
     def write_details_entry(self, out, var_doc):
         descr = self.descr(var_doc, indent=2)
+        if descr: descr = '<br />'+descr
+        else: descr = ''
         if var_doc.is_public: div_class = ''
         else: div_class = ' class="private"'
 

Modified: trunk/epydoc/src/epydoc/docwriter/html_css.py
===================================================================
--- trunk/epydoc/src/epydoc/docwriter/html_css.py	2006-09-06 19:29:30 UTC (rev 1357)
+++ trunk/epydoc/src/epydoc/docwriter/html_css.py	2006-09-06 20:06:18 UTC (rev 1358)
@@ -84,6 +84,8 @@
 h1.epydoc                   { margin: 0; font-size: +140%; font-weight: bold; }
 h2.epydoc                   { font-size: +130%; font-weight: bold; }
 h3.epydoc                   { font-size: +115%; font-weight: bold; }
+td h3.epydoc                { font-size: +115%; font-weight: bold;
+                              margin-bottom: 0; }
 table.navbar                { background: #a0c0ff; color: #000000;
                               border: 2px groove #c0d0d0; }
 table.navbar table          { color: #000000; }

Modified: trunk/epydoc/src/epydoc/markup/__init__.py
===================================================================
--- trunk/epydoc/src/epydoc/markup/__init__.py	2006-09-06 19:29:30 UTC (rev 1357)
+++ trunk/epydoc/src/epydoc/markup/__init__.py	2006-09-06 20:06:18 UTC (rev 1358)
@@ -245,7 +245,8 @@
         
         @return: A tuple C{(M{body}, M{fields})}, where C{M{body}} is
             the main body of this docstring, and C{M{fields}} is a list
-            of its fields.
+            of its fields.  If the resulting body is empty, return
+            C{None} for the body.
         @rtype: C{(L{ParsedDocstring}, list of L{Field})}
         @param errors: A list where any errors generated during
             splitting will be stored.  If no list is specified, then
@@ -336,7 +337,8 @@
 ##################################################
 class ConcatenatedDocstring:
     def __init__(self, *parsed_docstrings):
-        self._parsed_docstrings = parsed_docstrings
+        self._parsed_docstrings = [pds for pds in parsed_docstrings
+                                   if pds is not None]
         
     def split_fields(self, errors=None):
         bodies = []

Modified: trunk/epydoc/src/epydoc/markup/epytext.py
===================================================================
--- trunk/epydoc/src/epydoc/markup/epytext.py	2006-09-06 19:29:30 UTC (rev 1357)
+++ trunk/epydoc/src/epydoc/markup/epytext.py	2006-09-06 20:06:18 UTC (rev 1358)
@@ -2020,11 +2020,10 @@
 
         # Save the remaining docstring as the description..
         if tree.children and tree.children[0].children:
-            descr = tree
+            return ParsedEpytextDocstring(tree), fields
         else:
-            descr = None
+            return None, fields
 
-        return ParsedEpytextDocstring(descr), fields
     
     def index_terms(self):
         if self._terms is None:

Modified: trunk/epydoc/src/epydoc/markup/javadoc.py
===================================================================
--- trunk/epydoc/src/epydoc/markup/javadoc.py	2006-09-06 19:29:30 UTC (rev 1357)
+++ trunk/epydoc/src/epydoc/markup/javadoc.py	2006-09-06 20:06:18 UTC (rev 1358)
@@ -146,7 +146,10 @@
                 parsed_body = ParsedJavadocDocstring(body)
                 fields.append(Field(tag, arg, parsed_body))
 
-        return (descr, fields)
+        if pieces[0].strip():
+            return (descr, fields)
+        else:
+            return (None, fields)
 
     #////////////////////////////////////////////////////////////
     # HTML Output.

Modified: trunk/epydoc/src/epydoc/markup/restructuredtext.py
===================================================================
--- trunk/epydoc/src/epydoc/markup/restructuredtext.py	2006-09-06 19:29:30 UTC (rev 1357)
+++ trunk/epydoc/src/epydoc/markup/restructuredtext.py	2006-09-06 20:06:18 UTC (rev 1358)
@@ -164,7 +164,10 @@
         # Inherit docs
         visitor = _SplitFieldsTranslator(self._document, errors)
         self._document.walk(visitor)
-        return self, visitor.fields
+        if len(self._document.children) > 0:
+            return self, visitor.fields
+        else:
+            return None, visitor.fields
 
     def summary(self):
         # Inherit docs


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