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
diff --git a/docs/advanced/functions.rst b/docs/advanced/functions.rst
index 5131144..8788885 100644
--- a/docs/advanced/functions.rst
+++ b/docs/advanced/functions.rst
@@ -88,7 +88,7 @@
| | return value is referenced by Python. This is the default policy for |
| | property getters created via ``def_property``, ``def_readwrite``, etc. |
+--------------------------------------------------+----------------------------------------------------------------------------+
-| :enum:`return_value_policy::automatic` | This is the default return value policy, which falls back to the policy |
+| :enum:`return_value_policy::automatic` | **Default policy.** This policy falls back to the policy |
| | :enum:`return_value_policy::take_ownership` when the return value is a |
| | pointer. Otherwise, it uses :enum:`return_value::move` or |
| | :enum:`return_value::copy` for rvalue and lvalue references, respectively. |
@@ -159,7 +159,11 @@
========================
In addition to the above return value policies, further `call policies` can be
-specified to indicate dependencies between parameters. There is currently just
+specified to indicate dependencies between parameters. In general, call policies
+are required when the C++ object is any kind of container and another object is being
+added to the container.
+
+There is currently just
one policy named ``keep_alive<Nurse, Patient>``, which indicates that the
argument with index ``Patient`` should be kept alive at least until the
argument with index ``Nurse`` is freed by the garbage collector. Argument