From 18d1e459f411414fd6f3e9b87b01eccad3bc8b5d Mon Sep 17 00:00:00 2001 From: gentlegiantJGC Date: Mon, 17 Feb 2025 14:34:53 +0000 Subject: [PATCH 1/2] Improved reference_internal documentation Improved the wording to make it easier to understand and added a note about the policy falling back to move if the return value is not an lvalue reference or pointer. --- docs/advanced/functions.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/advanced/functions.rst b/docs/advanced/functions.rst index 372934b099..cae7bb9c57 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 | From 4ec3237fb28e2d0cc1ff3160c6c5b73416ef550f Mon Sep 17 00:00:00 2001 From: gentlegiantJGC Date: Thu, 20 Feb 2025 16:59:36 +0000 Subject: [PATCH 2/2] Added bold and ticket number --- docs/advanced/functions.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/advanced/functions.rst b/docs/advanced/functions.rst index cae7bb9c57..ff00c9c8ac 100644 --- a/docs/advanced/functions.rst +++ b/docs/advanced/functions.rst @@ -84,8 +84,8 @@ The following table provides an overview of available policies: | :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 | +| | **Otherwise this policy falls back to :enum:`return_value_policy::move` | +| | (see #5528).** 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 |