gh-128508: Add some docstrings to xml.dom.minidom

Lib/xml/dom/minidom.py

@@ -32,6 +32,7 @@
 
 
 class Node(xml.dom.Node):
+    """Define properties accessible on a DOM node."""
     namespaceURI = None # this is non-null only for elements and attributes
     parentNode = None
     ownerDocument = None
@@ -44,6 +45,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,10 +82,17 @@ def _get_lastChild(self):
             return self.childNodes[-1]
 
     def insertBefore(self, newChild, refChild):
+        """Insert a new DOM Node before an existing Node.
+
+        https://dom.spec.whatwg.org/#dom-node-insertbefore
+        The insertBefore(node, child) method, when invoked,
+        must return the result of pre-inserting node into
+        this before child.
+        See also https://dom.spec.whatwg.org/#concept-node-pre-insert
+        """
         if newChild.nodeType == self.DOCUMENT_FRAGMENT_NODE:
             for c in tuple(newChild.childNodes):
                 self.insertBefore(c, refChild)
-            ### The DOM does not clearly specify what to return in this case
             return newChild
         if newChild.nodeType not in self._child_node_types:
             raise xml.dom.HierarchyRequestErr(
@@ -112,6 +121,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 +139,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 +172,7 @@ def replaceChild(self, newChild, oldChild):
         return oldChild
 
     def removeChild(self, oldChild):
+        """Remove an existing child."""
         try:
             self.childNodes.remove(oldChild)
         except ValueError:
@@ -172,11 +184,16 @@ def removeChild(self, oldChild):
         oldChild.nextSibling = oldChild.previousSibling = None
         if oldChild.nodeType in _nodeTypes_with_children:
             _clear_id_cache(self)
-
         oldChild.parentNode = None
         return oldChild
 
     def normalize(self):
+        """Transform a node into its normalized form.
+
+        Removes empty exclusive Text nodes and concatenates the 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 +221,12 @@ def normalize(self):
         self.childNodes[:] = L
 
     def cloneNode(self, deep):
+        """Create and return a duplicate of this node.
+
+        Args:
+            deep (bool): 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):
@@ -1341,6 +1364,12 @@ def _get_internalSubset(self):
         return self.internalSubset
 
     def cloneNode(self, deep):
+        """Create and return a duplicate of this node.
+
+        Args:
+            deep (bool): 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)
@@ -1903,9 +1932,16 @@ 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.
+
+    Args:
+        node: The DOM node to clone
+        deep (bool): If True, recursively clone the node's descendants.
+                    If False, only clone the node itself.
+        newOwnerDocument: The document that will own the cloned node
+
+    Returns:
+        The cloned node
     """
     if node.ownerDocument.isSameNode(newOwnerDocument):
         operation = xml.dom.UserDataHandler.NODE_CLONED