feat: Support merging overload annotations into implementation

Issue-442: #442

Author: pawamoy

src/griffe/_internal/expressions.py

@@ -250,6 +250,22 @@ def is_generator(self) -> bool:
         """Whether this expression is a generator."""
         return isinstance(self, ExprSubscript) and self.canonical_name == "Generator"
 
+    @staticmethod
+    def _to_binop(elements: Sequence[Expr], op: str) -> ExprBinOp:
+        if len(elements) == 2:  # noqa: PLR2004
+            left, right = elements
+            if isinstance(left, Expr):
+                left = left.modernize()
+            if isinstance(right, Expr):
+                right = right.modernize()
+            return ExprBinOp(left=left, operator=op, right=right)
+
+        left = ExprSubscript._to_binop(elements[:-1], op=op)
+        right = elements[-1]
+        if isinstance(right, Expr):
+            right = right.modernize()
+        return ExprBinOp(left=left, operator=op, right=right)
+
 
 @dataclass(eq=True, slots=True)
 class ExprAttribute(Expr):
@@ -873,22 +889,6 @@ def iterate(self, *, flat: bool = True) -> Iterator[str | Expr]:
         yield from _yield(self.slice, flat=flat, outer_precedence=_OperatorPrecedence.NONE)
         yield "]"
 
-    @staticmethod
-    def _to_binop(elements: Sequence[Expr], op: str) -> ExprBinOp:
-        if len(elements) == 2:  # noqa: PLR2004
-            left, right = elements
-            if isinstance(left, Expr):
-                left = left.modernize()
-            if isinstance(right, Expr):
-                right = right.modernize()
-            return ExprBinOp(left=left, operator=op, right=right)
-
-        left = ExprSubscript._to_binop(elements[:-1], op=op)
-        right = elements[-1]
-        if isinstance(right, Expr):
-            right = right.modernize()
-        return ExprBinOp(left=left, operator=op, right=right)
-
     def modernize(self) -> ExprBinOp | ExprSubscript:
         if self.canonical_path == "typing.Union":
             return self._to_binop(self.slice.elements, op="|")  # type: ignore[union-attr]

src/griffe/_internal/merger.py

@@ -6,6 +6,7 @@
 from typing import TYPE_CHECKING
 
 from griffe._internal.exceptions import AliasResolutionError, CyclicAliasError
+from griffe._internal.expressions import Expr
 from griffe._internal.logger import logger
 
 if TYPE_CHECKING:
@@ -60,10 +61,30 @@ def _merge_stubs_overloads(obj: Module | Class, stubs: Module | Class) -> None:
     for function_name, overloads in list(stubs.overloads.items()):
         if overloads:
             with suppress(KeyError):
-                obj.get_member(function_name).overloads = overloads
+                _merge_overload_annotations(obj.get_member(function_name), overloads)
         del stubs.overloads[function_name]
 
 
+def _merge_overload_annotations(function: Function, overloads: list[Function]) -> None:
+    function.overloads = overloads
+    for parameter in function.parameters:
+        if parameter.annotation is None:
+            annotations = []
+            seen = set()
+            for overload in overloads:
+                with suppress(KeyError):
+                    annotation = overload.parameters[parameter.name].annotation
+                    str_annotation = str(annotation)
+                    if isinstance(annotation, Expr) and str_annotation not in seen:
+                        annotations.append(annotation)
+                        seen.add(str_annotation)
+            if annotations:
+                if len(annotations) == 1:
+                    parameter.annotation = annotations[0]
+                else:
+                    parameter.annotation = Expr._to_binop(annotations, op="|")
+
+
 def _merge_stubs_members(obj: Module | Class, stubs: Module | Class) -> None:
     # Merge imports to later know if objects coming from the stubs were imported.
     obj.imports.update(stubs.imports)