keep_alive call policy (analogous to Boost.Python's with_custodian_and_ward, fixes #62)
diff --git a/docs/advanced.rst b/docs/advanced.rst
index 43a3b1a..84ca73c 100644
--- a/docs/advanced.rst
+++ b/docs/advanced.rst
@@ -446,6 +446,33 @@
return m.ptr();
}
+
+Additional call policies
+========================
+
+In addition to the above return value policies, further `call policies` can be
+specified to indicate dependencies between parameters. There is currently just
+one policy named ``keep_alive<Nurse, Patient>``, which indicates that the
+argument with index ``Patient`` should be kept alive at least until the
+argument with index ``Nurse`` is freed by the garbage collector; argument
+indices start at one, while zero refers to the return value. Arbitrarily many
+call policies can be specified.
+
+For instance, binding code for a a list append operation that ties the lifetime
+of the newly added element to the underlying container might be declared as
+follows:
+
+.. code-block:: cpp
+
+ py::class_<List>(m, "List")
+ .def("append", &List::append, py::keep_alive<1, 2>());
+
+.. note::
+
+ ``keep_alive`` is analogous to the ``with_custodian_and_ward`` (if Nurse,
+ Patient != 0) and ``with_custodian_and_ward_postcall`` (if Nurse/Patient ==
+ 0) policies from Boost.Python.
+
Implicit type conversions
=========================