From 02bb545c815999d06b978ea783e7a07d744a3144 Mon Sep 17 00:00:00 2001
From: pan324 <freynek@gmail.com>
Date: Fri, 1 Nov 2024 12:51:18 +0100
Subject: [PATCH 1/4] added clinic docstrings to elementtree

---
 Modules/clinic/_elementtree.c.h | 160 +++++++++++++++++++++++++++-----
 1 file changed, 136 insertions(+), 24 deletions(-)

diff --git a/Modules/clinic/_elementtree.c.h b/Modules/clinic/_elementtree.c.h
index 1a5a820d1f00b5..b5d0311ec28a02 100644
--- a/Modules/clinic/_elementtree.c.h
+++ b/Modules/clinic/_elementtree.c.h
@@ -12,7 +12,12 @@ preserve
 PyDoc_STRVAR(_elementtree_Element_append__doc__,
 "append($self, subelement, /)\n"
 "--\n"
-"\n");
+"\n"
+"Add *subelement* to the end of this element.\n"
+"\n"
+"The new element will appear in document order after the last existing\n"
+"subelement (or directly after the text, if it's the first subelement),\n"
+"but before the end tag for this element.");
 
 #define _ELEMENTTREE_ELEMENT_APPEND_METHODDEF    \
     {"append", _PyCFunction_CAST(_elementtree_Element_append), METH_METHOD|METH_FASTCALL|METH_KEYWORDS, _elementtree_Element_append__doc__},
@@ -59,7 +64,11 @@ _elementtree_Element_append(ElementObject *self, PyTypeObject *cls, PyObject *co
 PyDoc_STRVAR(_elementtree_Element_clear__doc__,
 "clear($self, /)\n"
 "--\n"
-"\n");
+"\n"
+"Reset element.\n"
+"\n"
+"This function removes all subelements, clears all attributes, and sets\n"
+"the text and tail attributes to None.");
 
 #define _ELEMENTTREE_ELEMENT_CLEAR_METHODDEF    \
     {"clear", (PyCFunction)_elementtree_Element_clear, METH_NOARGS, _elementtree_Element_clear__doc__},
@@ -212,7 +221,10 @@ _elementtree_Element___setstate__(ElementObject *self, PyTypeObject *cls, PyObje
 PyDoc_STRVAR(_elementtree_Element_extend__doc__,
 "extend($self, elements, /)\n"
 "--\n"
-"\n");
+"\n"
+"Append subelements from a sequence.\n"
+"\n"
+"*elements* is a sequence with zero or more elements.");
 
 #define _ELEMENTTREE_ELEMENT_EXTEND_METHODDEF    \
     {"extend", _PyCFunction_CAST(_elementtree_Element_extend), METH_METHOD|METH_FASTCALL|METH_KEYWORDS, _elementtree_Element_extend__doc__},
@@ -255,7 +267,13 @@ _elementtree_Element_extend(ElementObject *self, PyTypeObject *cls, PyObject *co
 PyDoc_STRVAR(_elementtree_Element_find__doc__,
 "find($self, /, path, namespaces=None)\n"
 "--\n"
-"\n");
+"\n"
+"Find first matching element by tag name or path.\n"
+"\n"
+"*path* is a string having either an element tag or an XPath,\n"
+"*namespaces* is an optional mapping from namespace prefix to full name.\n"
+"\n"
+"Return the first matching element, or None if no element was found.");
 
 #define _ELEMENTTREE_ELEMENT_FIND_METHODDEF    \
     {"find", _PyCFunction_CAST(_elementtree_Element_find), METH_METHOD|METH_FASTCALL|METH_KEYWORDS, _elementtree_Element_find__doc__},
@@ -317,7 +335,16 @@ _elementtree_Element_find(ElementObject *self, PyTypeObject *cls, PyObject *cons
 PyDoc_STRVAR(_elementtree_Element_findtext__doc__,
 "findtext($self, /, path, default=None, namespaces=None)\n"
 "--\n"
-"\n");
+"\n"
+"Find text for first matching element by tag name or path.\n"
+"\n"
+"*path* is a string having either an element tag or an XPath,\n"
+"*default* is the value to return if the element was not found,\n"
+"*namespaces* is an optional mapping from namespace prefix to full name.\n"
+"\n"
+"Return text content of first matching element, or default value if\n"
+"none was found.  Note that if an element is found having no text\n"
+"content, the empty string is returned.");
 
 #define _ELEMENTTREE_ELEMENT_FINDTEXT_METHODDEF    \
     {"findtext", _PyCFunction_CAST(_elementtree_Element_findtext), METH_METHOD|METH_FASTCALL|METH_KEYWORDS, _elementtree_Element_findtext__doc__},
@@ -387,7 +414,13 @@ _elementtree_Element_findtext(ElementObject *self, PyTypeObject *cls, PyObject *
 PyDoc_STRVAR(_elementtree_Element_findall__doc__,
 "findall($self, /, path, namespaces=None)\n"
 "--\n"
-"\n");
+"\n"
+"Find all matching subelements by tag name or path.\n"
+"\n"
+"*path* is a string having either an element tag or an XPath,\n"
+"*namespaces* is an optional mapping from namespace prefix to full name.\n"
+"\n"
+"Returns list containing all matching elements in document order.");
 
 #define _ELEMENTTREE_ELEMENT_FINDALL_METHODDEF    \
     {"findall", _PyCFunction_CAST(_elementtree_Element_findall), METH_METHOD|METH_FASTCALL|METH_KEYWORDS, _elementtree_Element_findall__doc__},
@@ -449,7 +482,13 @@ _elementtree_Element_findall(ElementObject *self, PyTypeObject *cls, PyObject *c
 PyDoc_STRVAR(_elementtree_Element_iterfind__doc__,
 "iterfind($self, /, path, namespaces=None)\n"
 "--\n"
-"\n");
+"\n"
+"Find all matching subelements by tag name or path.\n"
+"\n"
+"*path* is a string having either an element tag or an XPath,\n"
+"*namespaces* is an optional mapping from namespace prefix to full name.\n"
+"\n"
+"Return an iterable yielding all matching elements in document order.");
 
 #define _ELEMENTTREE_ELEMENT_ITERFIND_METHODDEF    \
     {"iterfind", _PyCFunction_CAST(_elementtree_Element_iterfind), METH_METHOD|METH_FASTCALL|METH_KEYWORDS, _elementtree_Element_iterfind__doc__},
@@ -511,7 +550,15 @@ _elementtree_Element_iterfind(ElementObject *self, PyTypeObject *cls, PyObject *
 PyDoc_STRVAR(_elementtree_Element_get__doc__,
 "get($self, /, key, default=None)\n"
 "--\n"
-"\n");
+"\n"
+"Get element attribute.\n"
+"\n"
+"Equivalent to attrib.get, but some implementations may handle this a\n"
+"bit more efficiently.  *key* is what attribute to look for, and\n"
+"*default* is what to return if the attribute was not found.\n"
+"\n"
+"Returns a string containing the attribute value, or the default if\n"
+"attribute was not found.");
 
 #define _ELEMENTTREE_ELEMENT_GET_METHODDEF    \
     {"get", _PyCFunction_CAST(_elementtree_Element_get), METH_FASTCALL|METH_KEYWORDS, _elementtree_Element_get__doc__},
@@ -573,7 +620,19 @@ _elementtree_Element_get(ElementObject *self, PyObject *const *args, Py_ssize_t
 PyDoc_STRVAR(_elementtree_Element_iter__doc__,
 "iter($self, /, tag=None)\n"
 "--\n"
-"\n");
+"\n"
+"Create tree iterator.\n"
+"\n"
+"The iterator loops over the element and all subelements in document\n"
+"order, returning all elements with a matching tag.\n"
+"\n"
+"If the tree structure is modified during iteration, new or removed\n"
+"elements may or may not be included.  To get a stable set, use the\n"
+"list() function on the iterator, and loop over the resulting list.\n"
+"\n"
+"*tag* is what tags to look for (default is to return all elements)\n"
+"\n"
+"Return an iterator containing all the matching elements.");
 
 #define _ELEMENTTREE_ELEMENT_ITER_METHODDEF    \
     {"iter", _PyCFunction_CAST(_elementtree_Element_iter), METH_METHOD|METH_FASTCALL|METH_KEYWORDS, _elementtree_Element_iter__doc__},
@@ -633,7 +692,11 @@ _elementtree_Element_iter(ElementObject *self, PyTypeObject *cls, PyObject *cons
 PyDoc_STRVAR(_elementtree_Element_itertext__doc__,
 "itertext($self, /)\n"
 "--\n"
-"\n");
+"\n"
+"Create text iterator.\n"
+"\n"
+"The iterator loops over the element and all subelements in document\n"
+"order, returning all inner text.");
 
 #define _ELEMENTTREE_ELEMENT_ITERTEXT_METHODDEF    \
     {"itertext", _PyCFunction_CAST(_elementtree_Element_itertext), METH_METHOD|METH_FASTCALL|METH_KEYWORDS, _elementtree_Element_itertext__doc__},
@@ -654,7 +717,8 @@ _elementtree_Element_itertext(ElementObject *self, PyTypeObject *cls, PyObject *
 PyDoc_STRVAR(_elementtree_Element_insert__doc__,
 "insert($self, index, subelement, /)\n"
 "--\n"
-"\n");
+"\n"
+"Insert *subelement* at position *index*.");
 
 #define _ELEMENTTREE_ELEMENT_INSERT_METHODDEF    \
     {"insert", _PyCFunction_CAST(_elementtree_Element_insert), METH_FASTCALL, _elementtree_Element_insert__doc__},
@@ -699,7 +763,13 @@ _elementtree_Element_insert(ElementObject *self, PyObject *const *args, Py_ssize
 PyDoc_STRVAR(_elementtree_Element_items__doc__,
 "items($self, /)\n"
 "--\n"
-"\n");
+"\n"
+"Get element attributes as a sequence.\n"
+"\n"
+"The attributes are returned in arbitrary order.  Equivalent to\n"
+"attrib.items().\n"
+"\n"
+"Return a list of (name, value) tuples.");
 
 #define _ELEMENTTREE_ELEMENT_ITEMS_METHODDEF    \
     {"items", (PyCFunction)_elementtree_Element_items, METH_NOARGS, _elementtree_Element_items__doc__},
@@ -716,7 +786,11 @@ _elementtree_Element_items(ElementObject *self, PyObject *Py_UNUSED(ignored))
 PyDoc_STRVAR(_elementtree_Element_keys__doc__,
 "keys($self, /)\n"
 "--\n"
-"\n");
+"\n"
+"Get list of attribute names.\n"
+"\n"
+"Names are returned in an arbitrary order, just like an ordinary\n"
+"Python dict.  Equivalent to attrib.keys()");
 
 #define _ELEMENTTREE_ELEMENT_KEYS_METHODDEF    \
     {"keys", (PyCFunction)_elementtree_Element_keys, METH_NOARGS, _elementtree_Element_keys__doc__},
@@ -733,7 +807,13 @@ _elementtree_Element_keys(ElementObject *self, PyObject *Py_UNUSED(ignored))
 PyDoc_STRVAR(_elementtree_Element_makeelement__doc__,
 "makeelement($self, tag, attrib, /)\n"
 "--\n"
-"\n");
+"\n"
+"Create a new element with the same type.\n"
+"\n"
+"*tag* is a string containing the element name.\n"
+"*attrib* is a dictionary containing the element attributes.\n"
+"\n"
+"Do not call this method, use the SubElement factory function instead.");
 
 #define _ELEMENTTREE_ELEMENT_MAKEELEMENT_METHODDEF    \
     {"makeelement", _PyCFunction_CAST(_elementtree_Element_makeelement), METH_METHOD|METH_FASTCALL|METH_KEYWORDS, _elementtree_Element_makeelement__doc__},
@@ -782,7 +862,16 @@ _elementtree_Element_makeelement(ElementObject *self, PyTypeObject *cls, PyObjec
 PyDoc_STRVAR(_elementtree_Element_remove__doc__,
 "remove($self, subelement, /)\n"
 "--\n"
-"\n");
+"\n"
+"Remove matching subelement.\n"
+"\n"
+"Unlike the find methods, this method compares elements based on\n"
+"identity, NOT ON tag value or contents.  To remove subelements by\n"
+"other means, the easiest way is to use a list comprehension to\n"
+"select what elements to keep, and then use slice assignment to update\n"
+"the parent element.\n"
+"\n"
+"ValueError is raised if a matching element could not be found.");
 
 #define _ELEMENTTREE_ELEMENT_REMOVE_METHODDEF    \
     {"remove", (PyCFunction)_elementtree_Element_remove, METH_O, _elementtree_Element_remove__doc__},
@@ -810,7 +899,12 @@ _elementtree_Element_remove(ElementObject *self, PyObject *arg)
 PyDoc_STRVAR(_elementtree_Element_set__doc__,
 "set($self, key, value, /)\n"
 "--\n"
-"\n");
+"\n"
+"Set element attribute.\n"
+"\n"
+"Equivalent to attrib[key] = value, but some implementations may handle\n"
+"this a bit more efficiently.  *key* is what attribute to set, and\n"
+"*value* is the attribute value to set it to.");
 
 #define _ELEMENTTREE_ELEMENT_SET_METHODDEF    \
     {"set", _PyCFunction_CAST(_elementtree_Element_set), METH_FASTCALL, _elementtree_Element_set__doc__},
@@ -968,7 +1062,8 @@ _elementtree__set_factories(PyObject *module, PyObject *const *args, Py_ssize_t
 PyDoc_STRVAR(_elementtree_TreeBuilder_data__doc__,
 "data($self, data, /)\n"
 "--\n"
-"\n");
+"\n"
+"Add text to current element.");
 
 #define _ELEMENTTREE_TREEBUILDER_DATA_METHODDEF    \
     {"data", (PyCFunction)_elementtree_TreeBuilder_data, METH_O, _elementtree_TreeBuilder_data__doc__},
@@ -976,7 +1071,10 @@ PyDoc_STRVAR(_elementtree_TreeBuilder_data__doc__,
 PyDoc_STRVAR(_elementtree_TreeBuilder_end__doc__,
 "end($self, tag, /)\n"
 "--\n"
-"\n");
+"\n"
+"Close and return current Element.\n"
+"\n"
+"*tag* is the element name.");
 
 #define _ELEMENTTREE_TREEBUILDER_END_METHODDEF    \
     {"end", (PyCFunction)_elementtree_TreeBuilder_end, METH_O, _elementtree_TreeBuilder_end__doc__},
@@ -984,7 +1082,10 @@ PyDoc_STRVAR(_elementtree_TreeBuilder_end__doc__,
 PyDoc_STRVAR(_elementtree_TreeBuilder_comment__doc__,
 "comment($self, text, /)\n"
 "--\n"
-"\n");
+"\n"
+"Create a comment using the comment_factory.\n"
+"\n"
+"*text* is the text of the comment.");
 
 #define _ELEMENTTREE_TREEBUILDER_COMMENT_METHODDEF    \
     {"comment", (PyCFunction)_elementtree_TreeBuilder_comment, METH_O, _elementtree_TreeBuilder_comment__doc__},
@@ -992,7 +1093,11 @@ PyDoc_STRVAR(_elementtree_TreeBuilder_comment__doc__,
 PyDoc_STRVAR(_elementtree_TreeBuilder_pi__doc__,
 "pi($self, target, text=None, /)\n"
 "--\n"
-"\n");
+"\n"
+"Create a processing instruction using the pi_factory.\n"
+"\n"
+"*target* is the target name of the processing instruction.\n"
+"*text* is the data of the processing instruction, or ''.");
 
 #define _ELEMENTTREE_TREEBUILDER_PI_METHODDEF    \
     {"pi", _PyCFunction_CAST(_elementtree_TreeBuilder_pi), METH_FASTCALL, _elementtree_TreeBuilder_pi__doc__},
@@ -1026,7 +1131,8 @@ _elementtree_TreeBuilder_pi(TreeBuilderObject *self, PyObject *const *args, Py_s
 PyDoc_STRVAR(_elementtree_TreeBuilder_close__doc__,
 "close($self, /)\n"
 "--\n"
-"\n");
+"\n"
+"Flush builder buffers and return toplevel document Element.");
 
 #define _ELEMENTTREE_TREEBUILDER_CLOSE_METHODDEF    \
     {"close", (PyCFunction)_elementtree_TreeBuilder_close, METH_NOARGS, _elementtree_TreeBuilder_close__doc__},
@@ -1043,7 +1149,11 @@ _elementtree_TreeBuilder_close(TreeBuilderObject *self, PyObject *Py_UNUSED(igno
 PyDoc_STRVAR(_elementtree_TreeBuilder_start__doc__,
 "start($self, tag, attrs, /)\n"
 "--\n"
-"\n");
+"\n"
+"Open new element and return it.\n"
+"\n"
+"*tag* is the element name, *attrs* is a dict containing element\n"
+"attributes.");
 
 #define _ELEMENTTREE_TREEBUILDER_START_METHODDEF    \
     {"start", _PyCFunction_CAST(_elementtree_TreeBuilder_start), METH_FASTCALL, _elementtree_TreeBuilder_start__doc__},
@@ -1155,7 +1265,8 @@ _elementtree_XMLParser___init__(PyObject *self, PyObject *args, PyObject *kwargs
 PyDoc_STRVAR(_elementtree_XMLParser_close__doc__,
 "close($self, /)\n"
 "--\n"
-"\n");
+"\n"
+"Finish feeding data to parser and return element structure.");
 
 #define _ELEMENTTREE_XMLPARSER_CLOSE_METHODDEF    \
     {"close", (PyCFunction)_elementtree_XMLParser_close, METH_NOARGS, _elementtree_XMLParser_close__doc__},
@@ -1189,7 +1300,8 @@ _elementtree_XMLParser_flush(XMLParserObject *self, PyObject *Py_UNUSED(ignored)
 PyDoc_STRVAR(_elementtree_XMLParser_feed__doc__,
 "feed($self, data, /)\n"
 "--\n"
-"\n");
+"\n"
+"Feed encoded data to parser.");
 
 #define _ELEMENTTREE_XMLPARSER_FEED_METHODDEF    \
     {"feed", (PyCFunction)_elementtree_XMLParser_feed, METH_O, _elementtree_XMLParser_feed__doc__},

From 8a3724c513d07ecd4265151003d503298807c18d Mon Sep 17 00:00:00 2001
From: "blurb-it[bot]" <43283697+blurb-it[bot]@users.noreply.github.com>
Date: Fri, 1 Nov 2024 12:35:34 +0000
Subject: [PATCH 2/4] =?UTF-8?q?=F0=9F=93=9C=F0=9F=A4=96=20Added=20by=20blu?=
 =?UTF-8?q?rb=5Fit.?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../Documentation/2024-11-01-12-35-32.gh-issue-126273.t_qOoH.rst | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 Misc/NEWS.d/next/Documentation/2024-11-01-12-35-32.gh-issue-126273.t_qOoH.rst

diff --git a/Misc/NEWS.d/next/Documentation/2024-11-01-12-35-32.gh-issue-126273.t_qOoH.rst b/Misc/NEWS.d/next/Documentation/2024-11-01-12-35-32.gh-issue-126273.t_qOoH.rst
new file mode 100644
index 00000000000000..164a6d69a519e2
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2024-11-01-12-35-32.gh-issue-126273.t_qOoH.rst
@@ -0,0 +1 @@
+Added docstrings to certain xml.etree methods.

From dc2e4bb287b2de110184048cccc35fa723adfc5f Mon Sep 17 00:00:00 2001
From: pan324 <freynek@gmail.com>
Date: Fri, 1 Nov 2024 13:57:09 +0100
Subject: [PATCH 3/4] added docstrings to elementtree.c

---
 Modules/_elementtree.c          | 188 +++++++++++++++++++++++++++-----
 Modules/clinic/_elementtree.c.h |  41 ++++++-
 2 files changed, 200 insertions(+), 29 deletions(-)

diff --git a/Modules/_elementtree.c b/Modules/_elementtree.c
index e134e096e044b7..3afa9e4ace4c71 100644
--- a/Modules/_elementtree.c
+++ b/Modules/_elementtree.c
@@ -709,12 +709,17 @@ _elementtree.Element.append
     subelement: object(subclass_of='clinic_state()->Element_Type')
     /
 
+Add *subelement* to the end of this element.
+
+The new element will appear in document order after the last existing
+subelement (or directly after the text, if it's the first subelement),
+but before the end tag for this element.
 [clinic start generated code]*/
 
 static PyObject *
 _elementtree_Element_append_impl(ElementObject *self, PyTypeObject *cls,
                                  PyObject *subelement)
-/*[clinic end generated code: output=d00923711ea317fc input=8baf92679f9717b8]*/
+/*[clinic end generated code: output=d00923711ea317fc input=6f7560639b95fe1a]*/
 {
     elementtreestate *st = get_elementtree_state_by_cls(cls);
     if (element_add_subelement(st, self, subelement) < 0)
@@ -726,11 +731,15 @@ _elementtree_Element_append_impl(ElementObject *self, PyTypeObject *cls,
 /*[clinic input]
 _elementtree.Element.clear
 
+Reset element.
+
+This function removes all subelements, clears all attributes, and sets
+the text and tail attributes to None.
 [clinic start generated code]*/
 
 static PyObject *
 _elementtree_Element_clear_impl(ElementObject *self)
-/*[clinic end generated code: output=8bcd7a51f94cfff6 input=3c719ff94bf45dd6]*/
+/*[clinic end generated code: output=8bcd7a51f94cfff6 input=41b032d20869b1d6]*/
 {
     clear_extra(self);
 
@@ -1203,12 +1212,15 @@ _elementtree.Element.extend
     elements: object
     /
 
+Append subelements from a sequence.
+
+*elements* is a sequence with zero or more elements.
 [clinic start generated code]*/
 
 static PyObject *
 _elementtree_Element_extend_impl(ElementObject *self, PyTypeObject *cls,
                                  PyObject *elements)
-/*[clinic end generated code: output=3e86d37fac542216 input=6479b1b5379d09ae]*/
+/*[clinic end generated code: output=3e86d37fac542216 input=401ac1d07e13282b]*/
 {
     PyObject* seq;
     Py_ssize_t i;
@@ -1242,12 +1254,18 @@ _elementtree.Element.find
     path: object
     namespaces: object = None
 
+Find first matching element by tag name or path.
+
+*path* is a string having either an element tag or an XPath,
+*namespaces* is an optional mapping from namespace prefix to full name.
+
+Return the first matching element, or None if no element was found.
 [clinic start generated code]*/
 
 static PyObject *
 _elementtree_Element_find_impl(ElementObject *self, PyTypeObject *cls,
                                PyObject *path, PyObject *namespaces)
-/*[clinic end generated code: output=18f77d393c9fef1b input=94df8a83f956acc6]*/
+/*[clinic end generated code: output=18f77d393c9fef1b input=a67ae4f778d3b44b]*/
 {
     Py_ssize_t i;
     elementtreestate *st = get_elementtree_state_by_cls(cls);
@@ -1286,13 +1304,22 @@ _elementtree.Element.findtext
     default: object = None
     namespaces: object = None
 
+Find text for first matching element by tag name or path.
+
+*path* is a string having either an element tag or an XPath,
+*default* is the value to return if the element was not found,
+*namespaces* is an optional mapping from namespace prefix to full name.
+
+Return text content of first matching element, or default value if
+none was found.  Note that if an element is found having no text
+content, the empty string is returned.
 [clinic start generated code]*/
 
 static PyObject *
 _elementtree_Element_findtext_impl(ElementObject *self, PyTypeObject *cls,
                                    PyObject *path, PyObject *default_value,
                                    PyObject *namespaces)
-/*[clinic end generated code: output=6af7a2d96aac32cb input=32f252099f62a3d2]*/
+/*[clinic end generated code: output=6af7a2d96aac32cb input=e9c4bee136bd2cd9]*/
 {
     Py_ssize_t i;
     elementtreestate *st = get_elementtree_state_by_cls(cls);
@@ -1339,12 +1366,18 @@ _elementtree.Element.findall
     path: object
     namespaces: object = None
 
+Find all matching subelements by tag name or path.
+
+*path* is a string having either an element tag or an XPath,
+*namespaces* is an optional mapping from namespace prefix to full name.
+
+Returns list containing all matching elements in document order.
 [clinic start generated code]*/
 
 static PyObject *
 _elementtree_Element_findall_impl(ElementObject *self, PyTypeObject *cls,
                                   PyObject *path, PyObject *namespaces)
-/*[clinic end generated code: output=65e39a1208f3b59e input=7aa0db45673fc9a5]*/
+/*[clinic end generated code: output=65e39a1208f3b59e input=9e412b23984dd19a]*/
 {
     Py_ssize_t i;
     PyObject* out;
@@ -1388,12 +1421,18 @@ _elementtree.Element.iterfind
     path: object
     namespaces: object = None
 
+Find all matching subelements by tag name or path.
+
+*path* is a string having either an element tag or an XPath,
+*namespaces* is an optional mapping from namespace prefix to full name.
+
+Return an iterable yielding all matching elements in document order.
 [clinic start generated code]*/
 
 static PyObject *
 _elementtree_Element_iterfind_impl(ElementObject *self, PyTypeObject *cls,
                                    PyObject *path, PyObject *namespaces)
-/*[clinic end generated code: output=be5c3f697a14e676 input=88766875a5c9a88b]*/
+/*[clinic end generated code: output=be5c3f697a14e676 input=4a105ad9f64c97b4]*/
 {
     PyObject* tag = path;
     elementtreestate *st = get_elementtree_state_by_cls(cls);
@@ -1408,12 +1447,20 @@ _elementtree.Element.get
     key: object
     default: object = None
 
+Get element attribute.
+
+Equivalent to attrib.get, but some implementations may handle this a
+bit more efficiently.  *key* is what attribute to look for, and
+*default* is what to return if the attribute was not found.
+
+Returns a string containing the attribute value, or the default if
+attribute was not found.
 [clinic start generated code]*/
 
 static PyObject *
 _elementtree_Element_get_impl(ElementObject *self, PyObject *key,
                               PyObject *default_value)
-/*[clinic end generated code: output=523c614142595d75 input=ee153bbf8cdb246e]*/
+/*[clinic end generated code: output=523c614142595d75 input=773326625f9a3365]*/
 {
     if (self->extra && self->extra->attrib) {
         PyObject *attrib = Py_NewRef(self->extra->attrib);
@@ -1439,12 +1486,24 @@ _elementtree.Element.iter
     /
     tag: object = None
 
+Create tree iterator.
+
+The iterator loops over the element and all subelements in document
+order, returning all elements with a matching tag.
+
+If the tree structure is modified during iteration, new or removed
+elements may or may not be included.  To get a stable set, use the
+list() function on the iterator, and loop over the resulting list.
+
+*tag* is what tags to look for (default is to return all elements)
+
+Return an iterator containing all the matching elements.
 [clinic start generated code]*/
 
 static PyObject *
 _elementtree_Element_iter_impl(ElementObject *self, PyTypeObject *cls,
                                PyObject *tag)
-/*[clinic end generated code: output=bff29dc5d4566c68 input=f6944c48d3f84c58]*/
+/*[clinic end generated code: output=bff29dc5d4566c68 input=9b00ba7844661953]*/
 {
     if (PyUnicode_Check(tag)) {
         if (PyUnicode_GET_LENGTH(tag) == 1 && PyUnicode_READ_CHAR(tag, 0) == '*')
@@ -1466,11 +1525,15 @@ _elementtree.Element.itertext
     cls: defining_class
     /
 
+Create text iterator.
+
+The iterator loops over the element and all subelements in document
+order, returning all inner text.
 [clinic start generated code]*/
 
 static PyObject *
 _elementtree_Element_itertext_impl(ElementObject *self, PyTypeObject *cls)
-/*[clinic end generated code: output=fdeb2a3bca0ae063 input=a1ef1f0fc872a586]*/
+/*[clinic end generated code: output=fdeb2a3bca0ae063 input=eaffe70224da7f02]*/
 {
     elementtreestate *st = get_elementtree_state_by_cls(cls);
     return create_elementiter(st, self, Py_None, 1);
@@ -1517,12 +1580,13 @@ _elementtree.Element.insert
     subelement: object(subclass_of='clinic_state()->Element_Type')
     /
 
+Insert *subelement* at position *index*.
 [clinic start generated code]*/
 
 static PyObject *
 _elementtree_Element_insert_impl(ElementObject *self, Py_ssize_t index,
                                  PyObject *subelement)
-/*[clinic end generated code: output=990adfef4d424c0b input=9530f4905aa401ca]*/
+/*[clinic end generated code: output=990adfef4d424c0b input=2886a2266de15ed7]*/
 {
     Py_ssize_t i;
 
@@ -1555,11 +1619,17 @@ _elementtree_Element_insert_impl(ElementObject *self, Py_ssize_t index,
 /*[clinic input]
 _elementtree.Element.items
 
+Get element attributes as a sequence.
+
+The attributes are returned in arbitrary order.  Equivalent to
+attrib.items().
+
+Return a list of (name, value) tuples.
 [clinic start generated code]*/
 
 static PyObject *
 _elementtree_Element_items_impl(ElementObject *self)
-/*[clinic end generated code: output=6db2c778ce3f5a4d input=adbe09aaea474447]*/
+/*[clinic end generated code: output=6db2c778ce3f5a4d input=0b6e20d84bfddf7b]*/
 {
     if (!self->extra || !self->extra->attrib)
         return PyList_New(0);
@@ -1570,11 +1640,15 @@ _elementtree_Element_items_impl(ElementObject *self)
 /*[clinic input]
 _elementtree.Element.keys
 
+Get list of attribute names.
+
+Names are returned in an arbitrary order, just like an ordinary
+Python dict.  Equivalent to attrib.keys()
 [clinic start generated code]*/
 
 static PyObject *
 _elementtree_Element_keys_impl(ElementObject *self)
-/*[clinic end generated code: output=bc5bfabbf20eeb3c input=f02caf5b496b5b0b]*/
+/*[clinic end generated code: output=bc5bfabbf20eeb3c input=cb6ca1d9d0d4ca75]*/
 {
     if (!self->extra || !self->extra->attrib)
         return PyList_New(0);
@@ -1599,12 +1673,18 @@ _elementtree.Element.makeelement
     attrib: object(subclass_of='&PyDict_Type')
     /
 
+Create a new element with the same type.
+
+*tag* is a string containing the element name.
+*attrib* is a dictionary containing the element attributes.
+
+Do not call this method, use the SubElement factory function instead.
 [clinic start generated code]*/
 
 static PyObject *
 _elementtree_Element_makeelement_impl(ElementObject *self, PyTypeObject *cls,
                                       PyObject *tag, PyObject *attrib)
-/*[clinic end generated code: output=d50bb17a47077d47 input=589829dab92f26e8]*/
+/*[clinic end generated code: output=d50bb17a47077d47 input=04cafc31637e7b41]*/
 {
     PyObject* elem;
 
@@ -1626,11 +1706,20 @@ _elementtree.Element.remove
     subelement: object(subclass_of='clinic_state()->Element_Type')
     /
 
+Remove matching subelement.
+
+Unlike the find methods, this method compares elements based on
+identity, NOT ON tag value or contents.  To remove subelements by
+other means, the easiest way is to use a list comprehension to
+select what elements to keep, and then use slice assignment to update
+the parent element.
+
+ValueError is raised if a matching element could not be found.
 [clinic start generated code]*/
 
 static PyObject *
 _elementtree_Element_remove_impl(ElementObject *self, PyObject *subelement)
-/*[clinic end generated code: output=38fe6c07d6d87d1f input=6133e1d05597d5ee]*/
+/*[clinic end generated code: output=38fe6c07d6d87d1f input=7fcaa8131ee6bd89]*/
 {
     Py_ssize_t i;
     int rc;
@@ -1703,12 +1792,17 @@ _elementtree.Element.set
     value: object
     /
 
+Set element attribute.
+
+Equivalent to attrib[key] = value, but some implementations may handle
+this a bit more efficiently.  *key* is what attribute to set, and
+*value* is the attribute value to set it to.
 [clinic start generated code]*/
 
 static PyObject *
 _elementtree_Element_set_impl(ElementObject *self, PyObject *key,
                               PyObject *value)
-/*[clinic end generated code: output=fb938806be3c5656 input=1efe90f7d82b3fe9]*/
+/*[clinic end generated code: output=fb938806be3c5656 input=e2905872c19e2276]*/
 {
     PyObject* attrib;
 
@@ -2400,6 +2494,24 @@ _elementtree.TreeBuilder.__init__
     insert_comments: bool = False
     insert_pis: bool = False
 
+Generic element structure builder.
+
+This builder converts a sequence of start, data, and end method
+calls to a well-formed element structure.
+
+You can use this class to build an element structure using a custom XML
+parser, or a parser for some other XML-like format.
+
+*element_factory* is an optional element factory which is called
+to create new Element instances, as necessary.
+
+*comment_factory* is a factory to create comments to be used instead of
+the standard factory.  If *insert_comments* is false (the default),
+comments will not be inserted into the tree.
+
+*pi_factory* is a factory to create processing instructions to be used
+instead of the standard factory.  If *insert_pis* is false (the default),
+processing instructions will not be inserted into the tree.
 [clinic start generated code]*/
 
 static int
@@ -2408,7 +2520,7 @@ _elementtree_TreeBuilder___init___impl(TreeBuilderObject *self,
                                        PyObject *comment_factory,
                                        PyObject *pi_factory,
                                        int insert_comments, int insert_pis)
-/*[clinic end generated code: output=8571d4dcadfdf952 input=ae98a94df20b5cc3]*/
+/*[clinic end generated code: output=8571d4dcadfdf952 input=6f5480172be74fae]*/
 {
     if (element_factory != Py_None) {
         Py_XSETREF(self->element_factory, Py_NewRef(element_factory));
@@ -2927,11 +3039,12 @@ _elementtree.TreeBuilder.data
     data: object
     /
 
+Add text to current element.
 [clinic start generated code]*/
 
 static PyObject *
 _elementtree_TreeBuilder_data(TreeBuilderObject *self, PyObject *data)
-/*[clinic end generated code: output=69144c7100795bb2 input=a0540c532b284d29]*/
+/*[clinic end generated code: output=69144c7100795bb2 input=679b26864cecbde8]*/
 {
     return treebuilder_handle_data(self, data);
 }
@@ -2942,11 +3055,14 @@ _elementtree.TreeBuilder.end
     tag: object
     /
 
+Close and return current Element.
+
+*tag* is the element name.
 [clinic start generated code]*/
 
 static PyObject *
 _elementtree_TreeBuilder_end(TreeBuilderObject *self, PyObject *tag)
-/*[clinic end generated code: output=9a98727cc691cd9d input=22dc3674236f5745]*/
+/*[clinic end generated code: output=9a98727cc691cd9d input=9d161338282e5fac]*/
 {
     return treebuilder_handle_end(self, tag);
 }
@@ -2957,11 +3073,14 @@ _elementtree.TreeBuilder.comment
     text: object
     /
 
+Create a comment using the comment_factory.
+
+*text* is the text of the comment.
 [clinic start generated code]*/
 
 static PyObject *
 _elementtree_TreeBuilder_comment(TreeBuilderObject *self, PyObject *text)
-/*[clinic end generated code: output=22835be41deeaa27 input=47e7ebc48ed01dfa]*/
+/*[clinic end generated code: output=22835be41deeaa27 input=b1579b62bb9277e4]*/
 {
     return treebuilder_handle_comment(self, text);
 }
@@ -2973,12 +3092,16 @@ _elementtree.TreeBuilder.pi
     text: object = None
     /
 
+Create a processing instruction using the pi_factory.
+
+*target* is the target name of the processing instruction.
+*text* is the data of the processing instruction, or ''.
 [clinic start generated code]*/
 
 static PyObject *
 _elementtree_TreeBuilder_pi_impl(TreeBuilderObject *self, PyObject *target,
                                  PyObject *text)
-/*[clinic end generated code: output=21eb95ec9d04d1d9 input=349342bd79c35570]*/
+/*[clinic end generated code: output=21eb95ec9d04d1d9 input=d43881a05c1ee59c]*/
 {
     return treebuilder_handle_pi(self, target, text);
 }
@@ -3001,11 +3124,12 @@ treebuilder_done(TreeBuilderObject* self)
 /*[clinic input]
 _elementtree.TreeBuilder.close
 
+Flush builder buffers and return toplevel document Element.
 [clinic start generated code]*/
 
 static PyObject *
 _elementtree_TreeBuilder_close_impl(TreeBuilderObject *self)
-/*[clinic end generated code: output=b441fee3202f61ee input=f7c9c65dc718de14]*/
+/*[clinic end generated code: output=b441fee3202f61ee input=461e8391c6b73c5f]*/
 {
     return treebuilder_done(self);
 }
@@ -3017,12 +3141,16 @@ _elementtree.TreeBuilder.start
     attrs: object(subclass_of='&PyDict_Type')
     /
 
+Open new element and return it.
+
+*tag* is the element name, *attrs* is a dict containing element
+attributes.
 [clinic start generated code]*/
 
 static PyObject *
 _elementtree_TreeBuilder_start_impl(TreeBuilderObject *self, PyObject *tag,
                                     PyObject *attrs)
-/*[clinic end generated code: output=e7e9dc2861349411 input=7288e9e38e63b2b6]*/
+/*[clinic end generated code: output=e7e9dc2861349411 input=26cccb49c3b8b12f]*/
 {
     return treebuilder_handle_start(self, tag, attrs);
 }
@@ -3628,12 +3756,18 @@ _elementtree.XMLParser.__init__
     target: object = None
     encoding: str(accept={str, NoneType}) = None
 
+Element structure builder for XML source data based on the expat parser.
+
+*target* is an optional target object which defaults to an instance of the
+standard TreeBuilder class, *encoding* is an optional encoding string
+which if given, overrides the encoding specified in the XML file:
+http://www.iana.org/assignments/character-sets
 [clinic start generated code]*/
 
 static int
 _elementtree_XMLParser___init___impl(XMLParserObject *self, PyObject *target,
                                      const char *encoding)
-/*[clinic end generated code: output=3ae45ec6cdf344e4 input=7e716dd6e4f3e439]*/
+/*[clinic end generated code: output=3ae45ec6cdf344e4 input=90bef6f84e8c4490]*/
 {
     self->entity = PyDict_New();
     if (!self->entity)
@@ -3849,11 +3983,12 @@ expat_parse(elementtreestate *st, XMLParserObject *self, const char *data,
 /*[clinic input]
 _elementtree.XMLParser.close
 
+Finish feeding data to parser and return element structure.
 [clinic start generated code]*/
 
 static PyObject *
 _elementtree_XMLParser_close_impl(XMLParserObject *self)
-/*[clinic end generated code: output=d68d375dd23bc7fb input=ca7909ca78c3abfe]*/
+/*[clinic end generated code: output=d68d375dd23bc7fb input=177603f3353e644f]*/
 {
     /* end feeding data to parser */
 
@@ -3920,11 +4055,12 @@ _elementtree.XMLParser.feed
     data: object
     /
 
+Feed encoded data to parser.
 [clinic start generated code]*/
 
 static PyObject *
 _elementtree_XMLParser_feed(XMLParserObject *self, PyObject *data)
-/*[clinic end generated code: output=e42b6a78eec7446d input=fe231b6b8de3ce1f]*/
+/*[clinic end generated code: output=e42b6a78eec7446d input=9432a189100bc488]*/
 {
     /* feed data to parser */
 
diff --git a/Modules/clinic/_elementtree.c.h b/Modules/clinic/_elementtree.c.h
index b5d0311ec28a02..d71a328f9ea122 100644
--- a/Modules/clinic/_elementtree.c.h
+++ b/Modules/clinic/_elementtree.c.h
@@ -16,7 +16,7 @@ PyDoc_STRVAR(_elementtree_Element_append__doc__,
 "Add *subelement* to the end of this element.\n"
 "\n"
 "The new element will appear in document order after the last existing\n"
-"subelement (or directly after the text, if it's the first subelement),\n"
+"subelement (or directly after the text, if it\'s the first subelement),\n"
 "but before the end tag for this element.");
 
 #define _ELEMENTTREE_ELEMENT_APPEND_METHODDEF    \
@@ -931,6 +931,30 @@ _elementtree_Element_set(ElementObject *self, PyObject *const *args, Py_ssize_t
     return return_value;
 }
 
+PyDoc_STRVAR(_elementtree_TreeBuilder___init____doc__,
+"TreeBuilder(element_factory=None, *, comment_factory=None,\n"
+"            pi_factory=None, insert_comments=False, insert_pis=False)\n"
+"--\n"
+"\n"
+"Generic element structure builder.\n"
+"\n"
+"This builder converts a sequence of start, data, and end method\n"
+"calls to a well-formed element structure.\n"
+"\n"
+"You can use this class to build an element structure using a custom XML\n"
+"parser, or a parser for some other XML-like format.\n"
+"\n"
+"*element_factory* is an optional element factory which is called\n"
+"to create new Element instances, as necessary.\n"
+"\n"
+"*comment_factory* is a factory to create comments to be used instead of\n"
+"the standard factory.  If *insert_comments* is false (the default),\n"
+"comments will not be inserted into the tree.\n"
+"\n"
+"*pi_factory* is a factory to create processing instructions to be used\n"
+"instead of the standard factory.  If *insert_pis* is false (the default),\n"
+"processing instructions will not be inserted into the tree.");
+
 static int
 _elementtree_TreeBuilder___init___impl(TreeBuilderObject *self,
                                        PyObject *element_factory,
@@ -1097,7 +1121,7 @@ PyDoc_STRVAR(_elementtree_TreeBuilder_pi__doc__,
 "Create a processing instruction using the pi_factory.\n"
 "\n"
 "*target* is the target name of the processing instruction.\n"
-"*text* is the data of the processing instruction, or ''.");
+"*text* is the data of the processing instruction, or \'\'.");
 
 #define _ELEMENTTREE_TREEBUILDER_PI_METHODDEF    \
     {"pi", _PyCFunction_CAST(_elementtree_TreeBuilder_pi), METH_FASTCALL, _elementtree_TreeBuilder_pi__doc__},
@@ -1184,6 +1208,17 @@ _elementtree_TreeBuilder_start(TreeBuilderObject *self, PyObject *const *args, P
     return return_value;
 }
 
+PyDoc_STRVAR(_elementtree_XMLParser___init____doc__,
+"XMLParser(*, target=None, encoding=None)\n"
+"--\n"
+"\n"
+"Element structure builder for XML source data based on the expat parser.\n"
+"\n"
+"*target* is an optional target object which defaults to an instance of the\n"
+"standard TreeBuilder class, *encoding* is an optional encoding string\n"
+"which if given, overrides the encoding specified in the XML file:\n"
+"http://www.iana.org/assignments/character-sets");
+
 static int
 _elementtree_XMLParser___init___impl(XMLParserObject *self, PyObject *target,
                                      const char *encoding);
@@ -1348,4 +1383,4 @@ _elementtree_XMLParser__setevents(XMLParserObject *self, PyObject *const *args,
 exit:
     return return_value;
 }
-/*[clinic end generated code: output=bd28eba33d9c1f25 input=a9049054013a1b77]*/
+/*[clinic end generated code: output=e1abf1a477eeaf1a input=a9049054013a1b77]*/

From 35aaac30b5d6deb31cfd9652f93983e62e2582de Mon Sep 17 00:00:00 2001
From: pan324 <103143968+pan324@users.noreply.github.com>
Date: Fri, 1 Nov 2024 20:11:36 +0100
Subject: [PATCH 4/4] Update
 Misc/NEWS.d/next/Documentation/2024-11-01-12-35-32.gh-issue-126273.t_qOoH.rst

Co-authored-by: Peter Bierma <zintensitydev@gmail.com>
---
 .../2024-11-01-12-35-32.gh-issue-126273.t_qOoH.rst              | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Misc/NEWS.d/next/Documentation/2024-11-01-12-35-32.gh-issue-126273.t_qOoH.rst b/Misc/NEWS.d/next/Documentation/2024-11-01-12-35-32.gh-issue-126273.t_qOoH.rst
index 164a6d69a519e2..7904dc1461b2bc 100644
--- a/Misc/NEWS.d/next/Documentation/2024-11-01-12-35-32.gh-issue-126273.t_qOoH.rst
+++ b/Misc/NEWS.d/next/Documentation/2024-11-01-12-35-32.gh-issue-126273.t_qOoH.rst
@@ -1 +1 @@
-Added docstrings to certain xml.etree methods.
+Added docstrings to certain :class:`xml.etree.ElementTree` methods.