From 4c36fb7b1236fce25e00b63f357ccc36dc006662 Mon Sep 17 00:00:00 2001
From: Sergei Izmailov <sergei.a.izmailov@gmail.com>
Date: Tue, 1 Sep 2020 15:56:43 +0300
Subject: [PATCH] [DOC] avoid C++ types in docstrings (#2441)

* doc: avoid C++ types in docstrings

* A bit of rewording

* Another bit of rewording

* Third rewording
---
 docs/advanced/misc.rst | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/docs/advanced/misc.rst b/docs/advanced/misc.rst
index 7798462df..0a73dae7e 100644
--- a/docs/advanced/misc.rst
+++ b/docs/advanced/misc.rst
@@ -304,3 +304,34 @@ the default settings are restored to prevent unwanted side effects.
 
 .. [#f4] http://www.sphinx-doc.org
 .. [#f5] http://github.com/pybind/python_example
+
+.. _avoiding-cpp-types-in-docstrings:
+
+Avoiding C++ types in docstrings
+================================
+
+Docstrings are generated at the time of the declaration, e.g. when ``.def(...)`` is called.
+At this point parameter and return types should be known to pybind11.
+If a custom type is not exposed yet through a ``py::class_`` constructor or a custom type caster,
+its C++ type name will be used instead to generate the signature in the docstring:
+
+.. code-block:: text
+
+     |  __init__(...)
+     |      __init__(self: example.Foo, arg0: ns::Bar) -> None
+                                              ^^^^^^^
+
+
+This limitation can be circumvented by ensuring that C++ classes are registered with pybind11
+before they are used as a parameter or return type of a function:
+
+.. code-block:: cpp
+
+    PYBIND11_MODULE(example, m) {
+
+        auto pyFoo = py::class_<ns::Foo>(m, "Foo");
+        auto pyBar = py::class_<ns::Bar>(m, "Bar");
+
+        pyFoo.def(py::init<const ns::Bar&>());
+        pyBar.def(py::init<const ns::Foo&>());
+    }