gh-148428: Address review: docstring, doc markup, user-stream clear() test

Author: WYSIATI

Doc/library/xml.dom.pulldom.rst

@@ -147,11 +147,13 @@ DOMEventStream Objects
 
    .. method:: DOMEventStream.reset()
 
-   .. method:: DOMEventStream.clear()
+   .. method:: clear()
 
-      Release the parsing objects and close the underlying stream if it
-      was opened by :func:`parse`. Streams provided by the caller are not
-      closed. It is safe to call this method more than once.
+      Release references to the parser, the stream and the DOM builder,
+      and close the stream if it was opened by :func:`parse`. Streams
+      provided by the caller are not closed. It is safe to call this
+      method more than once. The event stream cannot be used after
+      calling this method.
 
       .. versionchanged:: next
          This method now closes the underlying stream if it was opened

Lib/test/test_pulldom.py

@@ -59,6 +59,13 @@ def test_clear_closes_owned_stream(self):
         self.assertTrue(stream.closed)
         events.clear()  # should not raise
 
+    def test_clear_does_not_close_user_stream(self):
+        with open(tstfile, 'rb') as f:
+            events = pulldom.parse(f)
+            list(events)
+            events.clear()
+            self.assertFalse(f.closed)
+
     def test_parse_semantics(self):
         """Test DOMEventStream parsing semantics."""
 

Lib/xml/dom/pulldom.py

@@ -281,7 +281,10 @@ def _emit(self):
         return rc
 
     def clear(self):
-        """clear(): Explicitly release parsing objects"""
+        """Release the parsing objects.
+
+        The stream is closed if it was opened by parse().
+        """
         if self._owns_stream and self.stream is not None:
             self.stream.close()
         if self.pulldom is not None: