doc updates
diff --git a/docs/advanced.rst b/docs/advanced.rst
index 366f06d..2067c89 100644
--- a/docs/advanced.rst
+++ b/docs/advanced.rst
@@ -468,7 +468,7 @@
| :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 @@
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::