doc updates

docs/advanced.rst

@@ -526,14 +526,13 @@ The following example snippet shows a use case of the
     non-determinism and segmentation faults, hence it is worth spending the
     time to understand all the different options in the table above.
 
-.. warning::
-
-    pybind11 tries to eliminate duplicate addresses by returning the same reference object.
-    If two addresses are the same, though they do not point to the same object semantically,
-    this may cause unexpected behaviour. An explicit policy should be used instead of
-    relying on `automatic`.
-    A common example is a reference to the first member of a class which has the same memory
-    location as its owning class.
+    It is worth highlighting one common issue where a method (e.g. a getter)
+    returns a reference (or pointer) to the first attribute of a class. In this
+    case, the class and attribute will be located at the same address in
+    memory, which pybind11 will recongnize and return the parent instance
+    instead of creating a new Python object that represents the attribute.
+    Here, the :enum:`return_value_policy::reference_internal` policy should be
+    used rather than relying on the automatic one.
 
 .. note::