trampoline simplification and documentation

docs/api_core.rst

@@ -1075,14 +1075,21 @@ the reference section on :ref:`class binding <class_binding>`.
 
 .. cpp:class:: next_overload
 
-   This special exception can be used to inform nanobind that a function
-   overload detected incompatible inputs. nanobind will then try other
-   overloads before reporting an error.
+   Raising this special exception from a bound function informs nanobind that
+   the function overload detected incompatible inputs. nanobind will then try
+   other overloads before reporting a ``TypeError``.
 
    This feature is useful when a multiple overloads of a function accept
    overlapping or identical input types (e.g. :cpp:class:`object`) and must run
    code at runtime to select the right overload.
 
+   You should probably write a thorough docstring explicing the expected inputs
+   in this case, since the behavior won't be obvious from the auto-generated
+   function signature list in the docstring. It can be frustrating when a
+   function call fails with an error message stating that the provided
+   arguments aren't compatible with any overload, when the associated error
+   message suggests otherwise.
+
    .. cpp:function:: next_overload()
 
       Constructor
@@ -1296,7 +1303,7 @@ parameter of :cpp:func:`module_::def`, :cpp:func:`class_::def`,
    - Index ``1`` refers to the first argument. In methods and constructors, index ``1``
      refers to the implicit ``this`` pointer, while regular arguments begin at index ``2``.
 
-    When the nurse or patient equal ``None``, the annotation does nothing. 
+    When the nurse or patient equal ``None``, the annotation does nothing.
 
     nanobind will raise an exception when the nurse object is neither a
     nanobind-registered type nor weak-referenceable.

docs/api_extra.rst

@@ -21,37 +21,51 @@ See the section on :ref:`trampolines <trampolines>` for further detail.
    function calls to a Python implementation. Refer to the documentation on
    :ref:`trampolines <trampolines>` to see how this macro can be used.
 
-.. c:macro:: NB_OVERRIDE(ret_type, base_type, func, ...)
+.. c:macro:: NB_OVERRIDE(func, ...)
 
    Dispatch the call to a Python method named ``"func"`` if it is overloaded on
-   the Python side. The method should return a result of type ``ret_type``.
-   Otherwise, call the C++ function ``base_type::func(...)``. Refer to the
-   documentation on :ref:`trampolines <trampolines>` to see how this macro can
-   be used.
+   the Python side, and forward the function arguments specified in the
+   variable length argument ``...``. Otherwise, call the C++ implementation
+   `func` in the base class.
 
-.. c:macro:: NB_OVERRIDE_PURE(ret_type, base_type, func, ...)
+   Refer to the documentation on :ref:`trampolines <trampolines>` to see how
+   this macro can be used.
+
+.. c:macro:: NB_OVERRIDE_PURE(func, ...)
 
    Dispatch the call to a Python method named ``"func"`` if it is overloaded on
-   the Python side. The method should return a result of type ``ret_type``.
-   Otherwise, raise an exception. This macro should be used when the C++
-   function is pure virtual. Refer to the documentation on :ref:`trampolines
-   <trampolines>` to see how this macro can be used.
+   the Python side, and forward the function arguments specified in the
+   variable length argument ``...``. Otherwise, raise an exception. This macro
+   should be used when the C++ function is pure virtual.
 
-.. c:macro:: NB_OVERRIDE_NAME(ret_type, base_type, name, func, ...)
+   Refer to the documentation on :ref:`trampolines <trampolines>` to see how
+   this macro can be used.
 
-   Dispatch the call to a Python method with custom identifier ``name`` if it is
-   overloaded on the Python side. The method should return a result of type
-   ``ret_type``. Otherwise, call the C++ function ``base_type::func(...)``. Refer
-   to the documentation on :ref:`trampolines <trampolines>` to see how this
-   macro can be used.
+.. c:macro:: NB_OVERRIDE_NAME(name, func, ...)
 
-.. c:macro:: NB_OVERRIDE_PURE_NAME(ret_type, base_type, name, func, ...)
+   Dispatch the call to a Python method named ``name`` if it is overloaded on
+   the Python side, and forward the function arguments specified in the
+   variable length argument ``...``. Otherwise, call the C++ function `func` in
+   the base class.
 
-   Dispatch the call to a Python method with the custom identifier ``name`` if it
-   is overloaded on the Python side. The method should return a result of type
-   ``ret_type``. Otherwise, raise an exception. This macro should be used when
-   the C++ function is pure virtual. Refer to the documentation on
-   :ref:`trampolines <trampolines>` to see how this macro can be used.
+   This function differs from :c:macro:`NB_OVERRIDE() <NB_OVERRIDE>` in that
+   C++ and Python functions can be named differently (e.g., ``operator+`` and
+   ``__add__``). Refer to the documentation on :ref:`trampolines <trampolines>`
+   to see how this macro can be used.
+
+.. c:macro:: NB_OVERRIDE_PURE_NAME(name, func, ...)
+
+   Dispatch the call to a Python method named ``name`` if it is overloaded on
+   the Python side, and forward the function arguments specified in the
+   variable length argument ``...``. Otherwise, raise an exception. This macro
+   should be used when the C++ function is pure virtual.
+
+   This function differs from :c:macro:`NB_OVERRIDE_PURE() <NB_OVERRIDE_PURE>`
+   in that C++ and Python functions can be named differently (e.g.,
+   ``operator+`` and ``__add__``). Although the C++ base implementation cannot
+   be called, its name is still important since nanobind uses it to infer the
+   return value type. Refer to the documentation on :ref:`trampolines
+   <trampolines>` to see how this macro can be used.
 
 .. _vector_bindings:
 

docs/changelog.rst

@@ -41,6 +41,8 @@ Version 0.2.0 (TBA)
       - :cpp:func:`.def_prop_ro_static() <class_::def_prop_ro_static>`,
         :cpp:func:`.def_prop_rw_static() <class_::def_prop_rw_static>`
 
+* Dropped the first two arguments of the :c:macro:`NB_OVERRIDE_*()
+  <NB_OVERRIDE>` macros that are not needed in nanobind.
 * Added casters for dense matrix/array types from the `Eigen library
   <https://eigen.tuxfamily.org/index.php?title=Main_Page>`_. (PR `#120
   <https://github.com/wjakob/nanobind/pull/120>`_).