added faq

docs/faq.rst

@@ -0,0 +1,37 @@
+Frequently asked questions
+##########################
+
+(under construction)
+
+Limitations involving reference arguments
+=========================================
+
+In C++, it's fairly common to pass arguments using mutable references or
+mutable pointers, which allows both read and write access to the value
+supplied by the caller. This is sometimes done for efficiency reasons, or to
+realize functions that have multiple return values. Here are two very basic
+examples:
+
+.. code-block:: cpp
+
+    void increment(int &i) { i++; }
+    void increment_ptr(int *i) { (*i)++; }
+
+In Python, all arguments are passed by reference, so there is no general
+issue in binding such code from Python.
+
+However, certain basic Python types (like ``str``, ``int``, ``bool``,
+``float``, etc.) are **immutable**. This means that the following attempt
+to port the function to Python doesn't have the same effect on the value
+provided by the caller -- in fact, it does nothing at all.
+
+.. code-block:: python
+
+    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.
+
+Although inconvenient, one workaround is to encapsulate the immutable types
+in a custom type that does allow modifications.

docs/index.rst

@@ -14,5 +14,6 @@ Contents:
    advanced
    cmake
    benchmark
+   faq
    reference
    changelog