Document in overloaded function is placed in wrong place

[KowerKoint]

When a function is overloaded, documentation comments is placed in wrong place.

For example, the C++ wrapper is below:

#include <iostream>
#include <pybind11/pybind11.h>
int add_int(int x, int y) {
    return x + y;
}
double add_double(double x, double y) {
    return x + y;
}

namespace py = pybind11;

PYBIND11_MODULE(python_example, m) {
    m.doc() = "pybind11 example plugin";
    m.def("add", &add_int, "Add x and y(int)", py::arg("x"), py::arg("y"));
    m.def("add", &add_double, "Add x and y(double)", py::arg("x"), py::arg("y"));
}

then, __init__.pyi below is generated:

"""pybind11 example plugin"""
from __future__ import annotations
import python_example
import typing

__all__ = [
    "add"
]

@typing.overload
def add(x: float, y: float) -> float:
    """
    Add x and y(int)

    Add x and y(double)
    """
@typing.overload
def add(x: int, y: int) -> int:
    pass

I expect it to be like below:

"""pybind11 example plugin"""
from __future__ import annotations
import python_example
import typing

__all__ = [
    "add"
]

@typing.overload
def add(x: float, y: float) -> float:
    """
    Add x and y(double)
    """
@typing.overload
def add(x: int, y: int) -> int:
    """
    Add x and y(int)
    """

help(add) prints separated documents, so I think this is pybind11-stubgen problem.

Is there a solution to fix it?

[sizmailov]

Hi!

Thanks for the report. This is not implemented, but it's doable. The only trick is to ensure that all custom (i.e. non-pybind) docstrings behave well too.

Note the upcoming function signature change in docstrings: https://github.com/pybind/pybind11/pull/2621

[sizmailov]

Closed with #112