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
     non-determinism and segmentation faults, hence it is worth spending the
     time to understand all the different options in the table above.
     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::
 .. note::