diff --git a/docs/advanced/functions.rst b/docs/advanced/functions.rst index 372934b09..cae7bb9c5 100644 --- a/docs/advanced/functions.rst +++ b/docs/advanced/functions.rst @@ -81,9 +81,11 @@ The following table provides an overview of available policies: | | it is no longer used. Warning: undefined behavior will ensue when the C++ | | | side deletes an object that is still referenced and used by Python. | +--------------------------------------------------+----------------------------------------------------------------------------+ -| :enum:`return_value_policy::reference_internal` | Indicates that the lifetime of the return value is tied to the lifetime | -| | of a parent object, namely the implicit ``this``, or ``self`` argument of | -| | the called method or property. Internally, this policy works just like | +| :enum:`return_value_policy::reference_internal` | If the return value is an lvalue reference or a pointer, the parent object | +| | (the implicit ``this``, or ``self`` argument of the called method or | +| | property) is kept alive for at least the lifespan of the return value. | +| | Otherwise this policy falls back to the policy | +| | :enum:`return_value_policy::move`. Internally, this policy works just like | | | :enum:`return_value_policy::reference` but additionally applies a | | | ``keep_alive<0, 1>`` *call policy* (described in the next section) that | | | prevents the parent object from being garbage collected as long as the |