Improved reference_internal documentation (#5528)
* 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.
* Added bold and ticket number
diff --git a/docs/advanced/functions.rst b/docs/advanced/functions.rst
index 372934b..ff00c9c 100644
--- a/docs/advanced/functions.rst
+++ b/docs/advanced/functions.rst
@@ -81,9 +81,11 @@
| | 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 :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 |
