From: Vladimír Vondruš Date: Mon, 22 Apr 2019 15:12:46 +0000 (+0200) Subject: doc: mention more pybind11 specifics. X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~cjwatson/git?a=commitdiff_plain;h=9be0ed4634d1c95358644e9f376fa2f8598d4110;p=blog.git doc: mention more pybind11 specifics. --- diff --git a/doc/documentation/python.rst b/doc/documentation/python.rst index 123858c6..62755e12 100644 --- 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 ` @@ -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`_ --------