Operator methods include a type signature of the additional overload

Closes #2269

Author: AWhetter

include/pybind11/pybind11.h

@@ -250,6 +250,7 @@ class cpp_function : public function {
         /* Generate a proper function signature */
         std::string signature;
         size_t type_index = 0, arg_index = 0;
+        std::string self_type("object");
         for (auto *pc = text; *pc != '\0'; ++pc) {
             const auto c = *pc;
 
@@ -279,9 +280,13 @@ class cpp_function : public function {
                     pybind11_fail("Internal error while parsing type signature (1)");
                 if (auto tinfo = detail::get_type_info(*t)) {
                     handle th((PyObject *) tinfo->type);
-                    signature +=
+                    std::string tname =
                         th.attr("__module__").cast<std::string>() + "." +
                         th.attr("__qualname__").cast<std::string>(); // Python 3.3+, but we backport it to earlier versions
+                    signature += tname;
+                    if (arg_index == 0 && rec->is_method) {
+                        self_type = tname;
+                    }
                 } else if (rec->is_new_style_constructor && arg_index == 0) {
                     // A new-style `__init__` takes `self` as `value_and_holder`.
                     // Rewrite it to the proper class type.
@@ -292,6 +297,9 @@ class cpp_function : public function {
                     std::string tname(t->name());
                     detail::clean_type_id(tname);
                     signature += tname;
+                    if (arg_index == 0 && rec->is_method) {
+                        self_type = tname;
+                    }
                 }
             } else {
                 signature += c;
@@ -377,9 +385,10 @@ class cpp_function : public function {
 
         std::string signatures;
         int index = 0;
+        const bool has_overloads = (chain || rec->is_operator);
         /* Create a nice pydoc rec including all signatures and
            docstrings of the functions in the overload chain */
-        if (chain && options::show_function_signatures()) {
+        if (has_overloads && options::show_function_signatures()) {
             // First a generic signature
             signatures += rec->name;
             signatures += "(*args, **kwargs)\n";
@@ -390,7 +399,7 @@ class cpp_function : public function {
         for (auto it = chain_start; it != nullptr; it = it->next) {
             if (options::show_function_signatures()) {
                 if (index > 0) signatures += "\n";
-                if (chain)
+                if (has_overloads)
                     signatures += std::to_string(++index) + ". ";
                 signatures += rec->name;
                 signatures += it->signature;
@@ -408,6 +417,16 @@ class cpp_function : public function {
                 if (options::show_function_signatures()) signatures += "\n";
             }
         }
+        if (rec->is_operator) {
+            signatures += "\n";
+            signatures += std::to_string(++index) + ". ";
+            signatures += rec->name;
+            signatures += "(";
+            if (rec->is_method) {
+                signatures += "self: " + self_type + ", ";
+            }
+            signatures += "*args, **kwargs) -> NotImplemented\n";
+        }
 
         /* Install docstring */
         PyCFunctionObject *func = (PyCFunctionObject *) m_ptr;

tests/test_operator_overloading.py

@@ -126,3 +126,15 @@ def test_nested():
     assert abase.value == 42
     del abase, b
     pytest.gc_collect()
+
+
+def test_docstring_includes_type_signature(msg):
+    """#2269: Docstring includes a type signature of the additional overload"""
+    assert msg(m.Vector2.__eq__.__doc__) == """
+        __eq__(*args, **kwargs)
+        Overloaded function.
+
+        1. __eq__(self: m.operators.Vector2, arg0: m.operators.Vector2) -> bool
+
+        2. __eq__(self: m.operators.Vector2, *args, **kwargs) -> NotImplemented
+    """