From 22f9bf835557ea6cd9a665b8d69600b86c99a978 Mon Sep 17 00:00:00 2001
From: =?utf8?q?Vladim=C3=ADr=20Vondru=C5=A1?= <mosra@centrum.cz>
Date: Sun, 15 Sep 2024 00:05:59 +0200
Subject: [PATCH] documentation/python: match the filtered builtin functions to
 the source.

So when a new Python version changes the docstring, it can be easily
found.
---
 documentation/python.py | 39 +++++++++++++++++++++++++++------------
 1 file changed, 27 insertions(+), 12 deletions(-)

diff --git a/documentation/python.py b/documentation/python.py
index 5aa328e1..122f5ef0 100755
--- a/documentation/python.py
+++ b/documentation/python.py
@@ -278,25 +278,40 @@ def is_underscored_and_undocumented(state: State, type, path, docstring):
 # Builtin dunder functions have hardcoded docstrings. This is totally useless
 # to have in the docs, so filter them out. Uh... kinda ugly.
 _filtered_builtin_functions = set([
+    # https://github.com/python/cpython/blob/401fff7423ca3c8bf1d02e594edfd1412616a559/Objects/typeobject.c#L10470
+    # Matching the order there, be sure to follow it when updating
+    ('__repr__', "Return repr(self)."),
+    ('__hash__', "Return hash(self)."),
+    ('__call__', "Call self as a function."),
+    ('__str__', "Return str(self)."),
+    ('__getattribute__', "Return getattr(self, name)."),
+    ('__getattr__', "Implement getattr(self, name)."),
+    ('__setattr__', "Implement setattr(self, name, value)."),
     ('__delattr__', "Implement delattr(self, name)."),
+    ('__lt__', "Return self<value."),
+    ('__le__', "Return self<=value."),
     ('__eq__', "Return self==value."),
-    ('__ge__', "Return self>=value."),
-    ('__getattribute__', "Return getattr(self, name)."),
+    ('__ne__', "Return self!=value."),
     ('__gt__', "Return self>value."),
-    ('__hash__', "Return hash(self)."),
-    ('__init__', "Initialize self.  See help(type(self)) for accurate signature."),
+    ('__ge__', "Return self>=value."),
+    ('__iter__', "Implement iter(self)."),
+    ('__next__', "Implement next(self)."),
+    ('__get__', "Return an attribute of instance, which is of type owner."),
+    ('__set__', "Set an attribute of instance to value."),
+    ('__delete__', "Delete an attribute of instance."),
+    ('__init__',
+        "Initialize self.  See help(type(self)) for accurate signature."),
+    ('__new__',
+        "Create and return a new object.  See help(type) for accurate signature."),
+    ('__del__', "Called when the instance is about to be destroyed."),
+    # TODO there's many more, maybe just add all?
+
+    # https://github.com/python/cpython/blob/401fff7423ca3c8bf1d02e594edfd1412616a559/Objects/typeobject.c#L7342
     ('__init_subclass__',
         "This method is called when a class is subclassed.\n\n"
         "The default implementation does nothing. It may be\n"
         "overridden to extend subclasses.\n"),
-    ('__le__', "Return self<=value."),
-    ('__lt__', "Return self<value."),
-    ('__ne__', "Return self!=value."),
-    ('__new__',
-        "Create and return a new object.  See help(type) for accurate signature."),
-    ('__repr__', "Return repr(self)."),
-    ('__setattr__', "Implement setattr(self, name, value)."),
-    ('__str__', "Return str(self)."),
+    # https://github.com/python/cpython/blob/401fff7423ca3c8bf1d02e594edfd1412616a559/Objects/typeobject.c#L7328
     ('__subclasshook__',
         "Abstract classes can override this to customize issubclass().\n\n"
         "This is invoked early on by abc.ABCMeta.__subclasscheck__().\n"
-- 
2.30.2