Minor cleanup: consistent return value, comments, docstring update.

git-svn-id: https://svn.code.sf.net/p/docutils/code/trunk/docutils@8386 929543f6-e4f2-0310-98a6-ba3bd3dd1d04

1 files changed, 22 insertions, 22 deletions

diff --git a/docutils/transforms/frontmatter.py b/docutils/transforms/frontmatter.py
index 3ef5dab55..1611456b5 100644
--- a/docutils/transforms/frontmatter.py
+++ b/docutils/transforms/frontmatter.py
@@ -63,15 +63,14 @@ class TitlePromoter(Transform):
         assert not (len(node) and isinstance(node[0], nodes.title))
         section, index = self.candidate_index(node)
         if index is None:
-            return None
+            return False
 
         # Transfer the section's attributes to the node:
-        # NOTE: Change second parameter to False to NOT replace
-        #       attributes that already exist in node with those in
-        #       section
-        # NOTE: Remove third parameter to NOT copy the 'source'
+        # NOTE: Change `replace` to False to NOT replace attributes that
+        #       already exist in node with those in section.
+        # NOTE: Remove `and_source` to NOT copy the 'source'
         #       attribute from section
-        node.update_all_atts_concatenating(section, True, True)
+        node.update_all_atts_concatenating(section, replace=True, and_source=True)
 
         # setup_child is called automatically for all nodes.
         node[:] = (section[:1]        # section title
@@ -79,7 +78,7 @@ class TitlePromoter(Transform):
                                       # node before the section
                    + section[1:])     # everything that was in the section
         assert isinstance(node[0], nodes.title)
-        return 1
+        return True
 
     def promote_subtitle(self, node):
         """
@@ -104,16 +103,15 @@ class TitlePromoter(Transform):
 
         subsection, index = self.candidate_index(node)
         if index is None:
-            return None
+            return False
         subtitle = nodes.subtitle()
 
         # Transfer the subsection's attributes to the new subtitle
-        # NOTE: Change second parameter to False to NOT replace
-        #       attributes that already exist in node with those in
-        #       section
-        # NOTE: Remove third parameter to NOT copy the 'source'
-        #       attribute from section
-        subtitle.update_all_atts_concatenating(subsection, True, True)
+        # NOTE: Change `replace` to False to NOT replace attributes
+        #       that already exist in node with those in section.
+        # NOTE: Remove `and_source` to NOT copy the 'source'
+        #       attribute from section.
+        subtitle.update_all_atts_concatenating(subsection, replace=True, and_source=True)
 
         # Transfer the contents of the subsection's title to the
         # subtitle:
@@ -124,7 +122,7 @@ class TitlePromoter(Transform):
                    + node[1:index]
                    # everything that was in the subsection:
                    + subsection[1:])
-        return 1
+        return True
 
     def candidate_index(self, node):
         """
@@ -134,8 +132,8 @@ class TitlePromoter(Transform):
         """
         index = node.first_child_not_matching_class(
             nodes.PreBibliographic)
-        if index is None or len(node) > (index + 1) or \
-               not isinstance(node[index], nodes.section):
+        if (index is None or len(node) > (index + 1)
+            or not isinstance(node[index], nodes.section)):
             return None, None
         else:
             return node[index], index
@@ -284,10 +282,9 @@ class SectionSubTitle(TitlePromoter):
         if not getattr(self.document.settings, 'sectsubtitle_xform', 1):
             return
         for section in self.document.traverse(nodes.section):
-            # On our way through the node tree, we are deleting
-            # sections, but we call self.promote_subtitle for those
-            # sections nonetheless.  To do: Write a test case which
-            # shows the problem and discuss on Docutils-develop.
+            # On our way through the node tree, we are modifying it
+            # but only the not-yet-visited part, so that the iterator
+            # returned by traverse() is not corrupted.
             self.promote_subtitle(section)
 
 
@@ -510,7 +507,10 @@ class DocInfo(Transform):
             raise
 
     def authors_from_one_paragraph(self, field):
-        """Return list of Text nodes for ";"- or ","-separated authornames."""
+        """Return list of Text nodes for authornames.
+        
+        The set of separators is locale dependent (default: ";"- or ",").
+        """
         # @@ keep original formatting? (e.g. ``:authors: A. Test, *et-al*``)
         text = ''.join(unicode(node)
                        for node in field[1].traverse(nodes.Text))