Improved reference_internal documentation

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 :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     |