Explain circular references and how to break them

[timothyqiu]

Closes #82882

• Adds circular reference related content in RefCounted
• Improves description of weakref behavior

[produno]

Fyi, there is a spelling mistake in the paragraph below the one you added.

garbage collection is free to destroy the referent

I believe this should be

garbage collection is free to destroy the reference ?

Sorry, ignore me :)

[AThousandShips]

"referent" means what's referred to, the target of the reference

[Mickeon]

While I'm glad the example in RefCounted exists, it feels quite verbose. It may sound easy to shrug off the next time someone falls into the same pit with a "Well, it's actually written right here", but perhaps it could be written differently to be easier to digest. Perhaps a more visual code example? Could that be necessary?

[timothyqiu]

I expect most people won't read this description because RefCounted is not a class that people will interact with directly.

The target audience for this description is someone who has encountered a circular reference problem and wants to find the cause and solution in the documentation.

Previously, the documentation of RefCounted didn't metion weak reference at all. So people experiencing problems can't get any relevant information from the documentation, unless they already know about the concept of weak references (but they don't need to rely on the documentation to find the solution in that case).

[YuriSizov]

This seems good to me, other than the suggestion that I've left.

[akien-mga]

Thanks!