Docs: minor clarifications (#590)
* Some clarifications to section on virtual fns
Primarily, I made it clear that PYBIND11_OVERLOAD_PURE_NAME is not "useful" but required in renaming situations. Also clarified that one should not bind to the trampoline helper class which I found tempting since it seems more explicit.
* Remove :emphasize-lines: from cpp block, seems to suppress formatting
* docs: emphasize default policy, clarify keep_alive
Emphasize the default return value policy since this statement is hidden in a wall of text.
Add a hint that call policies are probably required for container objects.
diff --git a/docs/advanced/classes.rst b/docs/advanced/classes.rst
index 5843e24..9d17364 100644
--- a/docs/advanced/classes.rst
+++ b/docs/advanced/classes.rst
@@ -79,7 +79,7 @@
PYBIND11_OVERLOAD_PURE(
std::string, /* Return type */
Animal, /* Parent class */
- go, /* Name of function */
+ go, /* Name of function in C++ (must match Python name) */
n_times /* Argument(s) */
);
}
@@ -90,7 +90,8 @@
a default implementation. There are also two alternate macros
:func:`PYBIND11_OVERLOAD_PURE_NAME` and :func:`PYBIND11_OVERLOAD_NAME` which
take a string-valued name argument between the *Parent class* and *Name of the
-function* slots. This is useful when the C++ and Python versions of the
+function* slots, which defines the name of function in Python. This is required
+when the C++ and Python versions of the
function have different names, e.g. ``operator()`` vs ``__call__``.
The binding code also needs a few minor adaptations (highlighted):
@@ -115,11 +116,20 @@
}
Importantly, pybind11 is made aware of the trampoline helper class by
-specifying it as an extra template argument to :class:`class_`. (This can also
+specifying it as an extra template argument to :class:`class_`. (This can also
be combined with other template arguments such as a custom holder type; the
order of template types does not matter). Following this, we are able to
define a constructor as usual.
+Bindings should be made against the actual class, not the trampoline helper class.
+
+.. code-block:: cpp
+
+ py::class_<Animal, PyAnimal /* <--- trampoline*/> animal(m, "Animal");
+ animal
+ .def(py::init<>())
+ .def("go", &PyAnimal::go); /* <--- THIS IS WRONG, use &Animal::go */
+
Note, however, that the above is sufficient for allowing python classes to
extend ``Animal``, but not ``Dog``: see ref:`virtual_and_inheritance` for the
necessary steps required to providing proper overload support for inherited