Prepend all function signatures to docstrings

Author: AWhetter

docs/advanced/misc.rst

@@ -302,6 +302,37 @@ Note that changes to the settings affect only function bindings created during t
 lifetime of the ``options`` instance. When it goes out of scope at the end of the module's init function,
 the default settings are restored to prevent unwanted side effects.
 
+Overloaded functions
+--------------------
+
+For overloaded functions, all function overload signatures are prepended to the
+docstring of a function, and all docstrings are concatenated together into sections
+that are separated by their function signature.
+
+For example:
+
+.. code-block:: pycon
+
+    >>> help(example.add)
+
+    add(...)
+     |      add(arg0: int, arg1: int) -> int
+     |      add(arg0: float, arg1: float) -> float
+     |
+     |      Overloaded function.
+     |
+     |      1. add(arg0: int, arg1: int) -> int
+     |
+     |      Add two integers together.
+     |
+     |      2. add(arg0: float, arg1: float) -> float
+     |
+     |      Add two floating points numbers together.
+
+Calling ``options.disable_function_signatures()``, as shown previously,
+will cause docstrings to be generated without the prepended function signatures
+and without the section headings.
+
 .. [#f4] http://www.sphinx-doc.org
 .. [#f5] http://github.com/pybind/python_example
 

include/pybind11/pybind11.h

@@ -453,10 +453,12 @@ class cpp_function : public function {
         /* Create a nice pydoc rec including all signatures and
            docstrings of the functions in the overload chain */
         if (chain && options::show_function_signatures()) {
-            // First a generic signature
-            signatures += rec->name;
-            signatures += "(*args, **kwargs)\n";
-            signatures += "Overloaded function.\n\n";
+            for (auto it = chain_start; it != nullptr; it = it->next) {
+                signatures += rec->name;
+                signatures += it->signature;
+                signatures += "\n";
+            }
+            signatures += "\nOverloaded function.\n\n";
         }
         // Then specific overload signatures
         bool first_user_def = true;

tests/test_factory_constructors.py

@@ -88,7 +88,11 @@ def test_init_factory_signature(msg):
     assert (
         msg(m.TestFactory1.__init__.__doc__)
         == """
-        __init__(*args, **kwargs)
+        __init__(self: m.factory_constructors.TestFactory1, arg0: m.factory_constructors.tag.unique_ptr_tag, arg1: int) -> None
+        __init__(self: m.factory_constructors.TestFactory1, arg0: str) -> None
+        __init__(self: m.factory_constructors.TestFactory1, arg0: m.factory_constructors.tag.pointer_tag) -> None
+        __init__(self: m.factory_constructors.TestFactory1, arg0: handle, arg1: int, arg2: handle) -> None
+
         Overloaded function.
 
         1. __init__(self: m.factory_constructors.TestFactory1, arg0: m.factory_constructors.tag.unique_ptr_tag, arg1: int) -> None