Commit 4c36fb7b by Sergei Izmailov Committed by GitHub

[DOC] avoid C++ types in docstrings (#2441)

* doc: avoid C++ types in docstrings

* A bit of rewording

* Another bit of rewording

* Third rewording
parent 3a89bffa
...@@ -304,3 +304,34 @@ the default settings are restored to prevent unwanted side effects. ...@@ -304,3 +304,34 @@ the default settings are restored to prevent unwanted side effects.
.. [#f4] http://www.sphinx-doc.org .. [#f4] http://www.sphinx-doc.org
.. [#f5] http://github.com/pybind/python_example .. [#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&>());
}
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment