Merge c68cb4d6f6 into 7099af8f5e

Lib/xml/dom/minidom.py

@@ -32,6 +32,10 @@
 
 
 class Node(xml.dom.Node):
+    """Base class representing a node in the DOM tree.
+
+    Provides core properties and methods that all DOM nodes must implement.
+    """
     namespaceURI = None # this is non-null only for elements and attributes
     parentNode = None
     ownerDocument = None
@@ -44,6 +48,7 @@ def __bool__(self):
         return True
 
     def toxml(self, encoding=None, standalone=None):
+        """Generate a string representation of a DOM."""
         return self.toprettyxml("", "", encoding, standalone)
 
     def toprettyxml(self, indent="\t", newl="\n", encoding=None,
@@ -80,6 +85,14 @@ def _get_lastChild(self):
             return self.childNodes[-1]
 
     def insertBefore(self, newChild, refChild):
+        """Insert a new DOM Node before an existing Node.
+
+        newChild
+          The new node to insert
+        refChild
+          The existing node that will be the next sibling of newChild.
+          If None, newChild is appended to the end.
+        """
         if newChild.nodeType == self.DOCUMENT_FRAGMENT_NODE:
             for c in tuple(newChild.childNodes):
                 self.insertBefore(c, refChild)
@@ -112,6 +125,7 @@ def insertBefore(self, newChild, refChild):
         return newChild
 
     def appendChild(self, node):
+        """Append a child node to an existing node."""
         if node.nodeType == self.DOCUMENT_FRAGMENT_NODE:
             for c in tuple(node.childNodes):
                 self.appendChild(c)
@@ -129,6 +143,7 @@ def appendChild(self, node):
         return node
 
     def replaceChild(self, newChild, oldChild):
+        """Replace child node *oldChild* with *newChild*."""
         if newChild.nodeType == self.DOCUMENT_FRAGMENT_NODE:
             refChild = oldChild.nextSibling
             self.removeChild(oldChild)
@@ -161,6 +176,7 @@ def replaceChild(self, newChild, oldChild):
         return oldChild
 
     def removeChild(self, oldChild):
+        """Remove an existing child."""
         try:
             self.childNodes.remove(oldChild)
         except ValueError:
@@ -177,6 +193,12 @@ def removeChild(self, oldChild):
         return oldChild
 
     def normalize(self):
+        """Transform this node into its normalized form.
+
+        Remove empty exclusive Text nodes and concatenate data of
+        remaining contiguous exclusive Text nodes into the first of
+        their nodes.
+        """
         L = []
         for child in self.childNodes:
             if child.nodeType == Node.TEXT_NODE:
@@ -204,6 +226,12 @@ def normalize(self):
         self.childNodes[:] = L
 
     def cloneNode(self, deep):
+        """Create and return a duplicate of this node.
+
+        deep
+          If True, recursively clone this node's descendants.
+          If False, clone only this node.
+        """
         return _clone_node(self, deep, self.ownerDocument or self)
 
     def isSupported(self, feature, version):
@@ -1334,6 +1362,12 @@ def _get_internalSubset(self):
         return self.internalSubset
 
     def cloneNode(self, deep):
+        """Create and return a duplicate of this node.
+
+        deep
+          If True, recursively clone this node's descendants.
+          If False, clone only this node.
+        """
         if self.ownerDocument is None:
             # it's ok
             clone = DocumentType(None)
@@ -1896,9 +1930,15 @@ def renameNode(self, n, namespaceURI, name):
 
 
 def _clone_node(node, deep, newOwnerDocument):
-    """
-    Clone a node and give it the new owner document.
-    Called by Node.cloneNode and Document.importNode
+    """Create and return a clone of a DOM node.
+
+    node
+      The DOM node to clone.
+    deep
+      If True, recursively clone the node's descendants.
+      If False, only clone the node itself.
+    newOwnerDocument
+      The document that will own the cloned node.
     """
     if node.ownerDocument.isSameNode(newOwnerDocument):
         operation = xml.dom.UserDataHandler.NODE_CLONED