Merge pull request #8841 from AWhetter/autodoc_signatures_without_backslash

Overloaded function signatures do not require a separating backslash

Author: tk0miya

doc/usage/extensions/autodoc.rst

@@ -529,15 +529,19 @@ There are also config values that you can set:
    looks like a signature, use the line as the signature and remove it from the
    docstring content.
 
-   If the signature line ends with backslash, autodoc considers the function has
-   multiple signatures and look at the next line of the docstring.  It is useful
-   for overloaded function.
+   autodoc will continue to look for multiple signature lines,
+   stopping at the first line that does not look like a signature.
+   This is useful for declaring overloaded function signatures.
 
    .. versionadded:: 1.1
    .. versionchanged:: 3.1
 
       Support overloaded signatures
 
+   .. versionchanged:: 4.0
+
+      Overloaded signatures do not need to be separated by a backslash
+
 .. confval:: autodoc_mock_imports
 
    This value contains a list of modules to be mocked up. This is useful when

sphinx/ext/autodoc/__init__.py

@@ -1191,20 +1191,17 @@ def _find_signature(self) -> Tuple[str, str]:
                     break
 
                 if line.endswith('\\'):
-                    multiline = True
                     line = line.rstrip('\\').rstrip()
-                else:
-                    multiline = False
 
                 # match first line of docstring against signature RE
                 match = py_ext_sig_re.match(line)
                 if not match:
-                    continue
+                    break
                 exmod, path, base, args, retann = match.groups()
 
                 # the base name must match ours
                 if base not in valid_names:
-                    continue
+                    break
 
                 # re-prepare docstring to ignore more leading indentation
                 tab_width = self.directive.state.document.settings.tab_width  # type: ignore
@@ -1218,13 +1215,6 @@ def _find_signature(self) -> Tuple[str, str]:
                     # subsequent signatures
                     self._signatures.append("(%s) -> %s" % (args, retann))
 
-                if multiline:
-                    # the signature have multiple signatures on docstring
-                    continue
-                else:
-                    # don't look any further
-                    break
-
             if result:
                 # finish the loop when signature found
                 break

tests/roots/test-ext-autodoc/target/docstring_signature.py

@@ -23,3 +23,9 @@ class E:
     def __init__(self):
         """E(foo: int, bar: int, baz: int) -> None \\
         E(foo: str, bar: str, baz: str) -> None"""
+
+
+class F:
+    def __init__(self):
+        """F(foo: int, bar: int, baz: int) -> None
+        F(foo: str, bar: str, baz: str) -> None"""

tests/test_ext_autodoc_configs.py

@@ -348,7 +348,11 @@ def test_autoclass_content_and_docstring_signature_class(app):
         '',
         '.. py:class:: E()',
         '   :module: target.docstring_signature',
-        ''
+        '',
+        '',
+        '.. py:class:: F()',
+        '   :module: target.docstring_signature',
+        '',
     ]
 
 
@@ -382,7 +386,12 @@ def test_autoclass_content_and_docstring_signature_init(app):
         '.. py:class:: E(foo: int, bar: int, baz: int) -> None',
         '              E(foo: str, bar: str, baz: str) -> None',
         '   :module: target.docstring_signature',
-        ''
+        '',
+        '',
+        '.. py:class:: F(foo: int, bar: int, baz: int) -> None',
+        '              F(foo: str, bar: str, baz: str) -> None',
+        '   :module: target.docstring_signature',
+        '',
     ]
 
 
@@ -421,6 +430,11 @@ def test_autoclass_content_and_docstring_signature_both(app):
         '              E(foo: str, bar: str, baz: str) -> None',
         '   :module: target.docstring_signature',
         '',
+        '',
+        '.. py:class:: F(foo: int, bar: int, baz: int) -> None',
+        '              F(foo: str, bar: str, baz: str) -> None',
+        '   :module: target.docstring_signature',
+        '',
     ]