From a22833d4eaa82ce06e9443e5025875c5001d93da Mon Sep 17 00:00:00 2001 From: Sergei Izmailov Date: Thu, 27 Aug 2020 21:29:10 +0300 Subject: [PATCH 1/4] doc: avoid C++ types in docstrings --- docs/advanced/misc.rst | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/docs/advanced/misc.rst b/docs/advanced/misc.rst index 7798462df7..a84e8160de 100644 --- a/docs/advanced/misc.rst +++ b/docs/advanced/misc.rst @@ -304,3 +304,31 @@ the default settings are restored to prevent unwanted side effects. .. [#f4] http://www.sphinx-doc.org .. [#f5] http://github.com/pybind/python_example + +.. _avoid-cpp-types-in-docstrings: + +Avoid C++ types in docstrings +============================= + +Most of docstrings are generated at the time of the declaration, e.g. when ``.def(...)`` is called. +At this point arguments/return types should be known to pybind11, otherwise C++ types would be used instead: + +.. code-block:: text + + | __init__(...) + | __init__(self: example.Foo, arg0: ns::Bar) -> None + ^^^^^^^ + + +This limitation can be tolerated by "forward declaring" bound classes: + +.. code-block:: cpp + + PYBIND11_MODULE(example, m) { + + auto pyFoo = py::class_(m, "Foo"); + auto pyBar = py::class_(m, "Bar"); + + pyFoo.def(py::init()); + pyBar.def(py::init()); + } From 7b9242c84826b36fa10e6dcedb6f97fe4429fa61 Mon Sep 17 00:00:00 2001 From: Sergei Izmailov Date: Fri, 28 Aug 2020 02:19:28 +0300 Subject: [PATCH 2/4] A bit of rewording --- docs/advanced/misc.rst | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/advanced/misc.rst b/docs/advanced/misc.rst index a84e8160de..d6a1dc7f23 100644 --- a/docs/advanced/misc.rst +++ b/docs/advanced/misc.rst @@ -305,13 +305,15 @@ the default settings are restored to prevent unwanted side effects. .. [#f4] http://www.sphinx-doc.org .. [#f5] http://github.com/pybind/python_example -.. _avoid-cpp-types-in-docstrings: +.. _avoiding-cpp-types-in-docstrings: -Avoid C++ types in docstrings -============================= +Avoiding C++ types in docstrings +================================ -Most of docstrings are generated at the time of the declaration, e.g. when ``.def(...)`` is called. -At this point arguments/return types should be known to pybind11, otherwise C++ types would be used instead: +Docstrings are generated at the time of the declaration, e.g. when ``.def(...)`` is called. +At this point argument 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 @@ -320,7 +322,7 @@ At this point arguments/return types should be known to pybind11, otherwise C++ ^^^^^^^ -This limitation can be tolerated by "forward declaring" bound classes: +This limitation can be circumvented by "forward declaring" bound classes: .. code-block:: cpp From cdb3f8784512852e991c850d99a17387afa5d580 Mon Sep 17 00:00:00 2001 From: Sergei Izmailov Date: Sun, 30 Aug 2020 15:21:42 +0300 Subject: [PATCH 3/4] Another bit of rewording --- docs/advanced/misc.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/advanced/misc.rst b/docs/advanced/misc.rst index d6a1dc7f23..53cc35539c 100644 --- a/docs/advanced/misc.rst +++ b/docs/advanced/misc.rst @@ -322,7 +322,8 @@ its C++ type name will be used instead to generate the signature in the docstrin ^^^^^^^ -This limitation can be circumvented by "forward declaring" bound classes: +This limitation can be circumvented by ensuring that C++ classes are registered with pybind11 +before they are used as a parameter to a function: .. code-block:: cpp From 267553792a66d12e386e7a3b0a9d585bc6565e3d Mon Sep 17 00:00:00 2001 From: Sergei Izmailov Date: Sun, 30 Aug 2020 20:14:05 +0300 Subject: [PATCH 4/4] Third rewording --- docs/advanced/misc.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/advanced/misc.rst b/docs/advanced/misc.rst index 53cc35539c..0a73dae7e7 100644 --- a/docs/advanced/misc.rst +++ b/docs/advanced/misc.rst @@ -311,7 +311,7 @@ Avoiding C++ types in docstrings ================================ Docstrings are generated at the time of the declaration, e.g. when ``.def(...)`` is called. -At this point argument and return types should be known to pybind11. +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: @@ -323,7 +323,7 @@ its C++ type name will be used instead to generate the signature in the docstrin This limitation can be circumvented by ensuring that C++ classes are registered with pybind11 -before they are used as a parameter to a function: +before they are used as a parameter or return type of a function: .. code-block:: cpp