docs: improved reference_internal documentation

[gentlegiantJGC]

Description

The documentation for the reference_internal return policy implies that py::keep_alive<0, 1>() is always applied but this isn't true.

There is quite a bit of confusion about the reference_internal return policy (myself included) stemming from this documentation.

Here are the related issues I have found.
#1764
#2618
#4124
#4236
#5046

These changes:

1. Improve the wording of the reference_internal documentation to make it easier to understand.
2. Add a note about the policy falling back to move if the return value is not an lvalue reference or pointer.

As documented thoroughtly in #4236 and #5046 the def_property family does not honor the keep_alive argument passed to it and #2618 also mentions it does not honor the call_guard argument. I think these issues should be fixed but should it be documented here until it is? The workaround is to use cpp_function and add those arguments there.

Fixes #1764
Fixes #2618
Fixes #4124

Suggested changelog entry:

Improved ``reference_internal`` policy documentation

[gentlegiantJGC]

The test failure is unrelated to changes I made

[rwgk]

That's a great and much needed clarification!

What do you think about:

• Making the "Otherwise ..." sentence bold, and ending it with "(see #5528)."

?

[gentlegiantJGC]

Done

[gentlegiantJGC]

I considered adding a line pointing out that keep_alive doesn't work when explicitly passed to the def_property methods because that is the users natural next response but it felt beyond the scope of it.
I added a compiler error in #5529 but I don't particularly like that because it will break existing code even if it didn't work correctly.
What would your suggestion be?

[rwgk]

Thanks @gentlegiantJGC!

Sorry I'm too busy right now to carefully think about your ideas for a more ambitious fix. I'll merge this, it's definitely useful!