Added warning about same-address-optimization
See https://github.com/pybind/pybind11/issues/254
diff --git a/docs/advanced.rst b/docs/advanced.rst
index f5b48d4..366f06d 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,6 +526,15 @@
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.
+
.. note::
The next section on :ref:`call_policies` discusses *call policies* that can be