[3.12] gh-101549: fix documentation of xml.etree.ElementInclude (GH-101550) (#117754)

Co-authored-by: Mikhail B <[email protected]>
Co-authored-by: Serhiy Storchaka <[email protected]>
Co-authored-by: Adam Turner <[email protected]>

Author: 4 people

Doc/library/xml.etree.elementtree.rst

@@ -835,33 +835,28 @@ Functions
 
 .. module:: xml.etree.ElementInclude
 
-.. function:: xml.etree.ElementInclude.default_loader( href, parse, encoding=None)
-   :module:
+.. function:: default_loader(href, parse, encoding=None)
 
-   Default loader. This default loader reads an included resource from disk.  *href* is a URL.
-   *parse* is for parse mode either "xml" or "text".  *encoding*
-   is an optional text encoding.  If not given, encoding is ``utf-8``.  Returns the
-   expanded resource.  If the parse mode is ``"xml"``, this is an ElementTree
-   instance.  If the parse mode is "text", this is a Unicode string.  If the
-   loader fails, it can return None or raise an exception.
+   Default loader. This default loader reads an included resource from disk.
+   *href* is a URL.  *parse* is for parse mode either "xml" or "text".
+   *encoding* is an optional text encoding.  If not given, encoding is ``utf-8``.
+   Returns the expanded resource.
+   If the parse mode is ``"xml"``, this is an :class:`~xml.etree.ElementTree.Element` instance.
+   If the parse mode is ``"text"``, this is a string.
+   If the loader fails, it can return ``None`` or raise an exception.
 
 
-.. function:: xml.etree.ElementInclude.include( elem, loader=None, base_url=None, \
-                                                max_depth=6)
-   :module:
+.. function:: include(elem, loader=None, base_url=None, max_depth=6)
 
-   This function expands XInclude directives.  *elem* is the root element.  *loader* is
-   an optional resource loader.  If omitted, it defaults to :func:`default_loader`.
+   This function expands XInclude directives in-place in tree pointed by *elem*.
+   *elem* is either the root :class:`~xml.etree.ElementTree.Element` or an
+   :class:`~xml.etree.ElementTree.ElementTree` instance to find such element.
+   *loader* is an optional resource loader.  If omitted, it defaults to :func:`default_loader`.
    If given, it should be a callable that implements the same interface as
    :func:`default_loader`.  *base_url* is base URL of the original file, to resolve
    relative include file references.  *max_depth* is the maximum number of recursive
-   inclusions.  Limited to reduce the risk of malicious content explosion. Pass a
-   negative value to disable the limitation.
-
-   Returns the expanded resource.  If the parse mode is
-   ``"xml"``, this is an ElementTree instance.  If the parse mode is "text",
-   this is a Unicode string.  If the loader fails, it can return None or
-   raise an exception.
+   inclusions.  Limited to reduce the risk of malicious content explosion.
+   Pass ``None`` to disable the limitation.
 
    .. versionchanged:: 3.9
       Added the *base_url* and *max_depth* parameters.

Lib/xml/etree/ElementInclude.py

@@ -79,8 +79,8 @@ class LimitedRecursiveIncludeError(FatalIncludeError):
 # @param parse Parse mode.  Either "xml" or "text".
 # @param encoding Optional text encoding (UTF-8 by default for "text").
 # @return The expanded resource.  If the parse mode is "xml", this
-#    is an ElementTree instance.  If the parse mode is "text", this
-#    is a Unicode string.  If the loader fails, it can return None
+#    is an Element instance.  If the parse mode is "text", this
+#    is a string.  If the loader fails, it can return None
 #    or raise an OSError exception.
 # @throws OSError If the loader fails to load the resource.
 
@@ -98,20 +98,21 @@ def default_loader(href, parse, encoding=None):
 ##
 # Expand XInclude directives.
 #
-# @param elem Root element.
+# @param elem Root Element or any ElementTree of a tree to be expanded
 # @param loader Optional resource loader.  If omitted, it defaults
 #     to {@link default_loader}.  If given, it should be a callable
 #     that implements the same interface as <b>default_loader</b>.
 # @param base_url The base URL of the original file, to resolve
 #     relative include file references.
 # @param max_depth The maximum number of recursive inclusions.
 #     Limited to reduce the risk of malicious content explosion.
-#     Pass a negative value to disable the limitation.
+#     Pass None to disable the limitation.
 # @throws LimitedRecursiveIncludeError If the {@link max_depth} was exceeded.
 # @throws FatalIncludeError If the function fails to include a given
 #     resource, or if the tree contains malformed XInclude elements.
-# @throws IOError If the function fails to load a given resource.
-# @returns the node or its replacement if it was an XInclude node
+# @throws OSError If the function fails to load a given resource.
+# @throws ValueError If negative {@link max_depth} is passed.
+# @returns None. Modifies tree pointed by {@link elem}
 
 def include(elem, loader=None, base_url=None,
             max_depth=DEFAULT_MAX_INCLUSION_DEPTH):