Cleanup the docs ElementTree a bit and describe the default_namespace parameter. In the code, replace the old outdated Doxygen-ish comment above ElementTree.write by a proper docstring.

eliben · eliben · commit e9af827fb168 · 2013-01-13T06:27:51.000-08:00
diff --git a/Doc/library/xml.etree.elementtree.rst b/Doc/library/xml.etree.elementtree.rst
@@ -428,7 +428,7 @@ Functions
    arguments.  Returns an element instance.
 
 
-.. function:: tostring(element, encoding="us-ascii", method="xml", *, \
+.. function:: tostring(element, encoding="us-ascii", method="xml", *,\
                        short_empty_elements=True)
 
    Generates a string representation of an XML element, including all
@@ -443,7 +443,7 @@ Functions
       The *short_empty_elements* parameter.
 
 
-.. function:: tostringlist(element, encoding="us-ascii", method="xml", *, \
+.. function:: tostringlist(element, encoding="us-ascii", method="xml", *,\
                            short_empty_elements=True)
 
    Generates a string representation of an XML element, including all
@@ -751,8 +751,9 @@ ElementTree Objects
       section root element.
 
 
-   .. method:: write(file, encoding="us-ascii", xml_declaration=None, \
-                     method="xml", *, short_empty_elements=True)
+   .. method:: write(file, encoding="us-ascii", xml_declaration=None,\
+                     default_namespace=None, method="xml", *,\
+                     short_empty_elements=True)
 
       Writes the element tree to a file, as XML.  *file* is a file name, or a
       :term:`file object` opened for writing.  *encoding* [1]_ is the output
@@ -761,7 +762,8 @@ ElementTree Objects
       file.  Use ``False`` for never, ``True`` for always, ``None``
       for only if not US-ASCII or UTF-8 or Unicode (default is ``None``).
       *method* is either ``"xml"``, ``"html"`` or ``"text"`` (default is
-      ``"xml"``).
+      ``"xml"``). *default_namespace* sets the default XML namespace (for
+      "xmlns").
       The keyword-only *short_empty_elements* parameter controls the formatting
       of elements that contain no content.  If *True* (the default), they are
       emitted as a single self-closed tag, otherwise they are emitted as a pair
diff --git a/Lib/xml/etree/ElementTree.py b/Lib/xml/etree/ElementTree.py
@@ -779,26 +779,26 @@ def iterfind(self, path, namespaces=None):
                 )
         return self._root.iterfind(path, namespaces)
 
-    ##
-    # Writes the element tree to a file, as XML.
-    #
-    # @def write(file, **options)
-    # @param file A file name, or a file object opened for writing.
-    # @param **options Options, given as keyword arguments.
-    # @keyparam encoding Optional output encoding (default is US-ASCII).
-    #     Use "unicode" to return a Unicode string.
-    # @keyparam method Optional output method ("xml", "html", "text" or
-    #     "c14n"; default is "xml").
-    # @keyparam xml_declaration Controls if an XML declaration should
-    #     be added to the file.  Use False for never, True for always,
-    #     None for only if not US-ASCII or UTF-8 or Unicode.  None is default.
-
     def write(self, file_or_filename,
               encoding=None,
               xml_declaration=None,
               default_namespace=None,
               method=None, *,
               short_empty_elements=True):
+        """Write the element tree to a file, as XML. 'file_or_filename' is a
+           file name or a file object opened for writing. 'encoding' is the
+           output encoding (default is US-ASCII). 'xml_declaration' controls
+           if an XML declaration should be added to the output. Use False
+           for never, True for always, None for only if not US-ASCII or
+           UTF-8 or Unicode (default is None). 'method' is either "xml"
+           (default), "html", "text" or "c14n".
+           'default_namespace' sets the default XML namespace (for "xmlns").
+           The keyword-only 'short_empty_elements' parameter controls the
+           formatting of elements that contain no content. If True (default),
+           they are emitted as a single self-closed tag, otherwise they are
+           emitted as a pair of start/end tags.
+
+        """
         if not method:
             method = "xml"
         elif method not in _serialize:
