From 7830e8509f2adc97ce9ee32bf99cd4b82089cc4c Mon Sep 17 00:00:00 2001 From: jbarlow83 Date: Fri, 13 Jan 2017 02:17:29 -0800 Subject: [PATCH] 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. --- docs/advanced/classes.rst | 16 +++++++++++++--- docs/advanced/functions.rst | 8 ++++++-- 2 files changed, 19 insertions(+), 5 deletions(-) diff --git a/docs/advanced/classes.rst b/docs/advanced/classes.rst index 5843e2447..9d17364b3 100644 --- a/docs/advanced/classes.rst +++ b/docs/advanced/classes.rst @@ -79,7 +79,7 @@ helper class that is defined as follows: 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 @@ functions, and :func:`PYBIND11_OVERLOAD` should be used for functions which have 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 @@ The binding code also needs a few minor adaptations (highlighted): } 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(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 513114458..878888541 100644 --- a/docs/advanced/functions.rst +++ b/docs/advanced/functions.rst @@ -88,7 +88,7 @@ The following table provides an overview of available policies: | | 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 @@ Additional call policies ======================== 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``, 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