From 4a48afb356c99a4ee5fe4c592d1fceebc8057f48 Mon Sep 17 00:00:00 2001
From: Wenzel Jakob <wenzel.jakob@epfl.ch>
Date: Wed, 9 Mar 2016 21:31:21 +0100
Subject: [PATCH] doc updates

---
 docs/cmake.rst | 21 ++++++++++++++++++---
 docs/faq.rst   | 24 ++++++++++++++++++++----
 2 files changed, 38 insertions(+), 7 deletions(-)

diff --git a/docs/cmake.rst b/docs/cmake.rst
index 238132f95..ace216758 100644
--- a/docs/cmake.rst
+++ b/docs/cmake.rst
@@ -1,11 +1,26 @@
+Build systems
+#############
+
+Building with setuptools
+========================
+
+For projects on PyPI, building with setuptools is the way to go. Sylvain Corlay
+has kindly provided an example project which shows how to set up everything,
+including automatic generation of documentation using Sphinx. Please refer to
+the [pbtest]_ repository.
+
+.. [pbtest] https://github.com/pybind/pbtest
+
 .. _cmake:
 
 Building with CMake
 ===================
 
-The following snippet should be a good starting point to create bindings across
-platforms. It assumes that the code is located in a file named :file:`example.cpp`,
-and that the pybind11 repository is located in a subdirectory named :file:`pybind11`.
+For C++ codebases that already have an existing CMake-based build system, the
+following snippet should be a good starting point to create bindings across
+platforms. It assumes that the code is located in a file named
+:file:`example.cpp`, and that the pybind11 repository is located in a
+subdirectory named :file:`pybind11`.
 
 .. code-block:: cmake
 
diff --git a/docs/faq.rst b/docs/faq.rst
index 45cb70ecb..f75498b02 100644
--- a/docs/faq.rst
+++ b/docs/faq.rst
@@ -30,8 +30,24 @@ provided by the caller -- in fact, it does nothing at all.
     def increment(i):
         i += 1 # nope..
 
-pybind11 is also affected by such language-level conventions, which means
-that binding ``increment`` or ``increment_ptr`` will also create Python functions that don't modify their arguments.
+pybind11 is also affected by such language-level conventions, which means that
+binding ``increment`` or ``increment_ptr`` will also create Python functions
+that don't modify their arguments.
+
+Although inconvenient, one workaround is to encapsulate the immutable types in
+a custom type that does allow modifications. 
+
+An other alternative involves binding a small wrapper lambda function that
+returns a tuple with all output arguments (see the remainder of the
+documentation for examples on binding lambda functions). An example:
+
+.. code-block:: cpp
+
+    int foo(int &i) { i++; return 123; }
+
+and the binding code
+
+.. code-block:: cpp
+
+   m.def("foo", [](int i) { int rv = foo(i); return std::make_tuple(rv, i); });
 
-Although inconvenient, one workaround is to encapsulate the immutable types
-in a custom type that does allow modifications.