doc updates

docs/advanced.rst

@@ -468,7 +468,7 @@ functions. The default policy is :enum:`return_value_policy::automatic`.
 | :enum:`return_value_policy::take_ownership`      | Reference an existing object (i.e. do not create a new copy) and take      |
 |                                                  | ownership. Python will call the destructor and delete operator when the    |
 |                                                  | object's reference count reaches zero. Undefined behavior ensues when the  |
-|                                                  | C++ side does the same.                                                   |
+|                                                  | C++ side does the same.                                                    |
 +--------------------------------------------------+----------------------------------------------------------------------------+
 | :enum:`return_value_policy::copy`                | Create a new copy of the returned object, which will be owned by Python.   |
 |                                                  | This policy is comparably safe because the lifetimes of the two instances  |
@@ -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::