doc: mention more pybind11 specifics.

diff --git a/doc/documentation/python.rst b/doc/documentation/python.rst
index 123858c64c02f479d33ed37b5acdbaa4d4e6aece..62755e126e11037b8697de370a37dc2f9406a707 100644 (file)
--- a/doc/documentation/python.rst
+++ b/doc/documentation/python.rst
@@ -41,6 +41,8 @@ Python docs
 .. role:: py(code)
     :language: py
 
+.. |wink| replace:: 😉
+
 A modern, mobile-friendly Sphinx-compatible Python documentation generator with
 a first-class search functionality. Generated by inspecting Python modules and
 using either embedded docstrings or external :abbr:`reST <reStructuredText>`
@@ -540,9 +542,26 @@ as such in the output.
 
 Similarly, property types are extracted from getter docstrings.
 
-The signature parsing can't handle all cases and, especially when templated C++
-type names leak through, it may fail to extract the argument names. If that
-happens, the function signature shows just an ellipsis (``…``).
+Unlike Python, pybind11 has a builtin support for overloaded functions ---
+depending on types passed to a function, it dispatches to a particular C++
+overload. The overloads are expanded in the output as well, meaning you can see
+one function mentioned more than once with different signatures.
+
+Because static methods in pybind11 are not decorated with :py:`@staticmethod`,
+they are detected based on presence of ``self`` as the first parameter --- if
+it's there, it's an instance method, otherwise it's a static method.
+
+.. block-warning:: Limitations
+
+    The static / instance method autodetection may fail when you name the first
+    argument of a static method as :cpp:`py::arg("self")`. Don't do that |wink|
+
+    The signature parsing can't handle all cases and, especially when templated
+    C++ type names leak through, it may fail to extract the argument names. If
+    that happens, the function signature shows just an ellipsis (``…``). On the
+    other hand, encountering a pure C++ type in a Python function signature
+    most probably points to a problem with the bindings as the type can't be
+    expressed with Python code.
 
 `Enums`_
 --------