From efc2aa7ee7c4a8142f15490315c940bd84aae87b Mon Sep 17 00:00:00 2001
From: Jason Rhinelander <jason@imaginary.ca>
Date: Wed, 10 Aug 2016 11:38:33 -0400
Subject: [PATCH] Removed obsolete documentation about duplicate address
 problems

It no longer applies since instances are now identified by both address
and type.
---
 docs/advanced.rst | 76 +++++------------------------------------------
 1 file changed, 7 insertions(+), 69 deletions(-)

diff --git a/docs/advanced.rst b/docs/advanced.rst
index a48ebd87b..4fd1d41e6 100644
--- a/docs/advanced.rst
+++ b/docs/advanced.rst
@@ -627,79 +627,17 @@ functions. The default policy is :enum:`return_value_policy::automatic`.
 
 .. warning::
 
-    Code with invalid call policies might access unitialized memory or free
-    data structures multiple times, which can lead to hard-to-debug
+    Code with invalid return value policies might access unitialized memory or
+    free data structures multiple times, which can lead to hard-to-debug
     non-determinism and segmentation faults, hence it is worth spending the
     time to understand all the different options in the table above.
 
-One important aspect regarding the above policies is that they only apply to
-instances which pybind11 has *not* seen before, in which case the policy
-clarifies essential questions about the return value's lifetime and ownership.
-
-When pybind11 knows the instance already (as identified via its address in
+One important aspect of the above policies is that they only apply to instances
+which pybind11 has *not* seen before, in which case the policy clarifies
+essential questions about the return value's lifetime and ownership.  When
+pybind11 knows the instance already (as identified by its type and address in
 memory), it will return the existing Python object wrapper rather than creating
-a copy. This means that functions which merely cast a reference (or pointer)
-into a different type don't do what one would expect:
-
-.. code-block:: cpp
-
-    A &func(B &value) { return (A&) value; }
-
-The wrapped version of this function will return the original ``B`` instance.
-To force a cast, the argument should be returned by value.
-
-More common (and equally problematic) are cases where methods (e.g. getters)
-return a pointer or reference to the first attribute of a class.
-
-.. code-block:: cpp
-    :emphasize-lines: 3, 13
-
-    class Example {
-    public:
-        Internal &get_internal() { return internal; }
-    private:
-        Internal internal;
-    };
-
-    PYBIND11_PLUGIN(example) {
-        py::module m("example", "pybind11 example plugin");
-
-        py::class_<Example>(m, "Example")
-            .def(py::init<>())
-            .def("get_internal", &Example::get_internal); /* Note: don't do this! */
-
-        return m.ptr();
-    }
-
-As in the above casting example, the instance and its 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. The special :enum:`return_value_policy::reference_internal` policy
-should be used in this case: it disables the same-address optimization and
-ensures that pybind11 returns a reference.
-The following example snippet shows the correct usage:
-
-.. code-block:: cpp
-
-    class Example {
-    public:
-        Internal &get_internal() { return internal; }
-    private:
-        Internal internal;
-    };
-
-    PYBIND11_PLUGIN(example) {
-        py::module m("example", "pybind11 example plugin");
-
-        py::class_<Example>(m, "Example")
-            .def(py::init<>())
-            .def("get_internal", &Example::get_internal, "Return the internal data",
-                                 py::return_value_policy::reference_internal);
-
-        return m.ptr();
-    }
-
-
+a copy.
 
 .. note::