gh-44871: Document the exceptions raised by the DOM interface

The DOM requires InvalidCharacterErr for an invalid XML name,
WrongDocumentErr for a node created by another document, and
HierarchyRequestErr for making a node a descendant of itself.  None of
this was documented.

Author: serhiy-storchaka

Doc/library/xml.dom.minidom.rst

@@ -266,6 +266,13 @@ rules apply:
   .. versionchanged:: next
      Previously, :attr:`~xml.dom.Attr.specified` was always ``False``.
 
+* The constraints of the DOM are now enforced,
+  and the corresponding exceptions are raised.
+
+  .. versionchanged:: next
+     Previously, many invalid operations silently succeeded
+     and produced an invalid document.
+
 The following interfaces have no implementation in :mod:`!xml.dom.minidom`:
 
 * :class:`DOMTimeStamp`

Doc/library/xml.dom.rst

@@ -232,6 +232,8 @@ DOM Level 2 added the ability to create new :class:`Document` and
    *qualifiedName*, *publicId*, and *systemId* strings, representing the
    information contained in an XML document type declaration.
 
+   Raise :exc:`InvalidCharacterErr` if the name is not a valid XML name.
+
 
 .. _dom-node-objects:
 
@@ -457,6 +459,10 @@ for each node type are:
    children, returning *newChild*. If the node was already in
    the tree, it is removed first.
 
+   Raise :exc:`WrongDocumentErr` if *newChild* was created by another
+   document, and :exc:`HierarchyRequestErr` if it is this node itself or
+   its ancestor.
+
 
 .. method:: Node.insertBefore(newChild, refChild)
 
@@ -465,6 +471,10 @@ for each node type are:
    *newChild* is returned. If *refChild* is ``None``, it inserts *newChild* at the
    end of the children's list.
 
+   Raise :exc:`WrongDocumentErr` if *newChild* was created by another
+   document, and :exc:`HierarchyRequestErr` if it is this node itself or
+   its ancestor.
+
 
 .. method:: Node.removeChild(oldChild)
 
@@ -479,6 +489,10 @@ for each node type are:
    Replace an existing node with a new node. It must be the case that  *oldChild*
    is a child of this node; if not, :exc:`ValueError` is raised.
 
+   Raise :exc:`WrongDocumentErr` if *newChild* was created by another
+   document, and :exc:`HierarchyRequestErr` if it is this node itself or
+   its ancestor.
+
 
 .. method:: Node.normalize()
 
@@ -665,6 +679,8 @@ inherits properties from :class:`Node`.
    document when it is created.  You need to explicitly insert it with one of the
    other methods such as :meth:`~Node.insertBefore` or :meth:`~Node.appendChild`.
 
+   Raise :exc:`InvalidCharacterErr` if the name is not a valid XML name.
+
 
 .. method:: Document.createElementNS(namespaceURI, tagName)
 
@@ -673,6 +689,8 @@ inherits properties from :class:`Node`.
    need to explicitly insert it with one of the other methods such as
    :meth:`~Node.insertBefore` or :meth:`~Node.appendChild`.
 
+   Raise :exc:`InvalidCharacterErr` if the name is not a valid XML name.
+
 
 .. method:: Document.createTextNode(data)
 
@@ -686,6 +704,8 @@ inherits properties from :class:`Node`.
    Create and return a new entity reference node.
    The node is not inserted into the document when it is created.
 
+   Raise :exc:`InvalidCharacterErr` if the name is not a valid XML name.
+
    .. versionadded:: next
 
 
@@ -702,6 +722,8 @@ inherits properties from :class:`Node`.
    *data* passed as parameters.  As with the other creation methods, this one does
    not insert the node into the tree.
 
+   Raise :exc:`InvalidCharacterErr` if the name is not a valid XML name.
+
 
 .. method:: Document.createAttribute(name)
 
@@ -710,6 +732,8 @@ inherits properties from :class:`Node`.
    :meth:`~Element.setAttributeNode` on the appropriate :class:`Element` object
    to use the newly created attribute instance.
 
+   Raise :exc:`InvalidCharacterErr` if the name is not a valid XML name.
+
 
 .. method:: Document.createAttributeNS(namespaceURI, qualifiedName)
 
@@ -718,6 +742,8 @@ inherits properties from :class:`Node`.
    element.  You must use :meth:`~Element.setAttributeNode` on the appropriate
    :class:`Element` object to use the newly created attribute instance.
 
+   Raise :exc:`InvalidCharacterErr` if the name is not a valid XML name.
+
 
 .. method:: Document.getElementById(id)
 
@@ -854,6 +880,8 @@ of that class.
 
    Set an attribute value from a string.
 
+   Raise :exc:`InvalidCharacterErr` if the name is not a valid XML name.
+
 
 .. method:: Element.setAttributeNode(newAttr)
 
@@ -862,6 +890,8 @@ of that class.
    occurs, the old attribute node will be returned.  If *newAttr* is already in use,
    :exc:`InuseAttributeErr` will be raised.
 
+   Raise :exc:`WrongDocumentErr` if *newAttr* was created by another document.
+
 
 .. method:: Element.setAttributeNodeNS(newAttr)
 
@@ -871,12 +901,16 @@ of that class.
    returned.  If *newAttr* is already in use, :exc:`InuseAttributeErr` will be
    raised.
 
+   Raise :exc:`WrongDocumentErr` if *newAttr* was created by another document.
+
 
 .. method:: Element.setAttributeNS(namespaceURI, qname, value)
 
    Set an attribute value from a string, given a *namespaceURI* and a *qname*.
    Note that a qname is the whole attribute name.  This is different than above.
 
+   Raise :exc:`InvalidCharacterErr` if the name is not a valid XML name.
+
 
 .. _dom-attr-objects:
 
@@ -982,13 +1016,19 @@ NamedNodeMap Objects
    Add *node* to the map, using its :attr:`~Attr.name` as the key.
    Return the node which it replaces, or ``None`` if it replaces no node.
 
+   Raise :exc:`WrongDocumentErr` if *node* was created by another document,
+   and :exc:`InuseAttributeErr` if it belongs to another element.
+
 
 .. method:: NamedNodeMap.setNamedItemNS(node)
 
    Add *node* to the map,
    using its namespace URI and local name as the key.
    Return the node which it replaces, or ``None`` if it replaces no node.
 
+   Raise :exc:`WrongDocumentErr` if *node* was created by another document,
+   and :exc:`InuseAttributeErr` if it belongs to another element.
+
 
 .. method:: NamedNodeMap.removeNamedItem(name)