format-docstring 0.2.0__tar.gz → 0.2.2__tar.gz

{format_docstring-0.2.0 → format_docstring-0.2.2}/.pre-commit-config.yaml

@@ -57,6 +57,11 @@ repos:
     rev: 0.0.11
     hooks:
       - id: markdown-toc-creator
+  - repo: https://github.com/jsh9/markdown-heading-numbering
+    rev: 0.1.0
+    hooks:
+      - id: markdown-heading-numbering
+        exclude: ^CHANGELOG\.md$
   - repo: local
     hooks:
       - id: format-docstring

{format_docstring-0.2.0 → format_docstring-0.2.2}/AGENTS.md

@@ -3,7 +3,7 @@
 This guide briefs coding agents working on `format-docstring`. Use it to get
 oriented before making changes.
 
-## Quick Snapshot
+## 1. Quick Snapshot
 
 - Formats NumPy-style docstrings (with experimental Google support) in `.py`
   files and Jupyter notebooks while preserving surrounding code.
@@ -13,7 +13,7 @@ oriented before making changes.
   `jupyter-notebook-parser`, and `tomli/tomllib` for configuration loading.
 - Version is sourced dynamically in `format_docstring/__init__.py`.
 
-## Repository Layout
+## 2. Repository Layout
 
 - `format_docstring/main_py.py` – Click CLI for Python files; validates input
   and delegates to `PythonFileFixer`.
@@ -33,7 +33,7 @@ oriented before making changes.
 - `tests/` – Pytest suite with fixture-driven cases in `tests/test_data/`; see
   `tests/helpers.py` for fixture loading helpers.
 
-## Implementation Notes
+## 3. Implementation Notes
 
 - `docstring_rewriter.fix_src` parses with `ast.parse`, collects docstring
   literals, and rewrites source slices using absolute offsets from
@@ -44,6 +44,8 @@ oriented before making changes.
   redundant `, optional`, and forward references keep their original quoting.
 - Return annotations are likewise projected into `Returns`/`Yields` sections,
   mirroring tuple element splits when the docstring already enumerates them.
+- `Raises` section entries are treated like signature lines in the NumPy
+  wrapper so exception names stay untouched while descriptions wrap.
 - Wrapping honors NumPy section heuristics, rST constructs, code fences,
   `Examples` prompts, and literal blocks introduced by `::`.
 - `_normalize_signature_segment` flattens multiline annotations via
@@ -57,7 +59,7 @@ oriented before making changes.
 - Notebook fixer round-trips JSON via `json.dump(..., indent=1)` and rewrites
   cells only when content changes, preserving magics with `reconstruct_source`.
 
-## Configuration
+## 4. Configuration
 
 - User-facing configuration lives under `[tool.format_docstring]` inside
   `pyproject.toml` and supports `line_length`, `docstring_style`, `exclude`,
@@ -68,7 +70,7 @@ oriented before making changes.
 - Default exclude pattern is `\.git|\.tox|\.pytest_cache`; tests tweak it as
   needed.
 
-## Development Workflow
+## 5. Development Workflow
 
 - Install: `pip install -e .` for the project,
   `pip install -r requirements.dev` for tooling.
@@ -83,17 +85,20 @@ oriented before making changes.
   `format-docstring-jupyter --help`.
 - Pre-commit: `pre-commit run -a`.
 
-## Testing Notes
+## 6. Testing Notes
 
 - Fixture files under `tests/test_data/line_wrap` and
   `tests/test_data/end_to_end` use `LINE_LENGTH: <int>` headers followed by
   `BEFORE`/`AFTER` sections split by `**********`.
+- Regression fixture
+  `tests/test_data/end_to_end/numpy/signature_dont_sync_raises.txt` guards
+  against mutating exception names in `Raises` blocks.
 - `tests/test_playground.py` focuses on regression snippets;
   `tests/test_config.py` exercises config discovery and CLI overrides.
 - When modifying wrapping rules, update both the helper (`line_wrap_utils.py`)
   and the corresponding expectation files in `tests/test_data/`.
 
-## Style Guidance
+## 7. Style Guidance
 
 - Formatting rules mirror `muff.toml` (line length 79, single quotes, NumPy
   docstring convention). Respect these when adding code.
@@ -101,7 +106,7 @@ oriented before making changes.
   content, and add regression cases whenever handling around literal sections
   or tables changes.
 
-## What is a "signature line"?
+## 8. What is a "signature line"?
 
 They are the lines in the docstring where input and return args are defined,
 for example, in this docstring:

{format_docstring-0.2.0 → format_docstring-0.2.2}/CHANGELOG.md

@@ -6,6 +6,20 @@ The format is based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.2] - 2024-10-20
+
+- Added
+  - Formatting support for type hints and default values in class docstrings
+- Full diff
+  - https://github.com/jsh9/format-docstring/compare/0.2.1...0.2.2
+
+## [0.2.1] - 2025-10-20
+
+- Fixed
+  - A bug where raised exceptions in docstrings are incorrectly changed
+- Full diff
+  - https://github.com/jsh9/format-docstring/compare/0.2.0...0.2.1
+
 ## [0.2.0] - 2025-10-20
 
 - Added

{format_docstring-0.2.0 → format_docstring-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: format-docstring
-Version: 0.2.0
+Version: 0.2.2
 Summary: A Python formatter to wrap/adjust docstring lines
 Author-email: jsh9 <25124332+jsh9@users.noreply.github.com>
 Maintainer-email: jsh9 <25124332+jsh9@users.noreply.github.com>

{format_docstring-0.2.0 → format_docstring-0.2.2}/format_docstring/base_fixer.py

@@ -15,7 +15,7 @@ class BaseFixer:
     ----------
     path : str
         Target file or directory to process.
-    exclude_pattern : str, default='\.git|\.tox|\.pytest_cache'
+    exclude_pattern : str, default=r'\.git|\.tox|\.pytest_cache'
         Regular expression describing paths to skip.
     verbose : str, default='default'
         Verbosity mode; ``'diff'`` prints unified diffs for rewritten files.

{format_docstring-0.2.0 → format_docstring-0.2.2}/format_docstring/docstring_rewriter.py

@@ -221,6 +221,53 @@ def _collect_param_metadata(
     return metadata
 
 
+def _collect_class_metadata(
+        node: ast.ClassDef,
+        source_code: str,
+) -> tuple[ParameterMetadata, ParameterMetadata]:
+    """
+    Build metadata for class docstrings using ``__init__`` and class attrs.
+    """
+    init_metadata: ParameterMetadata = {}
+    attribute_metadata: ParameterMetadata = {}
+
+    init_method: ast.FunctionDef | None = None
+    for stmt in node.body:
+        if isinstance(stmt, ast.FunctionDef) and stmt.name == '__init__':
+            init_method = stmt
+            break
+
+    if init_method is not None:
+        init_metadata = _collect_param_metadata(init_method, source_code)
+        # ``self``/``cls`` rarely appear in docstrings; drop to avoid noise.
+        init_metadata.pop('self', None)
+        init_metadata.pop('cls', None)
+
+    for stmt in node.body:
+        if isinstance(stmt, ast.AnnAssign):
+            target = stmt.target
+            if not isinstance(target, ast.Name):
+                continue
+
+            annotation = _render_signature_piece(stmt.annotation, source_code)
+            default = _render_signature_piece(stmt.value, source_code)
+            attribute_metadata[target.id] = (annotation, default)
+            continue
+
+        if isinstance(stmt, ast.Assign):
+            if len(stmt.targets) != 1:
+                continue
+
+            assign_target = stmt.targets[0]
+            if not isinstance(assign_target, ast.Name):
+                continue
+
+            # Record that this attribute explicitly has no annotation/default.
+            attribute_metadata[assign_target.id] = ('', None)
+
+    return init_metadata, attribute_metadata
+
+
 def fix_src(
         source_code: str,
         *,
@@ -255,7 +302,7 @@ def fix_src(
     spans directly in the original text to preserve non-docstring formatting
     and comments.
     """
-    tree: ast.Module = ast.parse(source_code)
+    tree: ast.Module = ast.parse(source_code, type_comments=True)
     line_starts: list[int] = calc_line_starts(source_code)
 
     replacements: list[tuple[int, int, str]] = []
@@ -387,10 +434,20 @@ def build_replacement_docstring(
     )
 
     param_metadata: ParameterMetadata | None = None
+    attribute_metadata: ParameterMetadata | None = None
     return_annotation: str | None = None
     if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
         param_metadata = _collect_param_metadata(node, source_code)
         return_annotation = _render_signature_piece(node.returns, source_code)
+    elif isinstance(node, ast.ClassDef):
+        init_metadata, class_attr_metadata = _collect_class_metadata(
+            node, source_code
+        )
+        if init_metadata:
+            param_metadata = init_metadata
+
+        if class_attr_metadata:
+            attribute_metadata = class_attr_metadata
 
     wrapped: str = wrap_docstring(
         doc,
@@ -400,6 +457,7 @@ def build_replacement_docstring(
         fix_rst_backticks=fix_rst_backticks,
         function_param_metadata=param_metadata,
         function_return_annotation=return_annotation,
+        class_attribute_metadata=attribute_metadata,
     )
 
     new_literal: str | None = rebuild_literal(original_literal, wrapped)
@@ -521,6 +579,7 @@ def wrap_docstring(
         fix_rst_backticks: bool = True,
         function_param_metadata: ParameterMetadata | None = None,
         function_return_annotation: str | None = None,
+        class_attribute_metadata: ParameterMetadata | None = None,
 ) -> str:
     """
     Wrap a docstring to the given line length (stub).
@@ -544,6 +603,9 @@ def wrap_docstring(
     function_return_annotation : str | None, default=None
         The function's return annotation text (normalized), used to keep
         ``Returns``/``Yields`` signature lines synchronized.
+    class_attribute_metadata : ParameterMetadata | None, default=None
+        Attribute metadata for class docstrings (names mapped to annotations
+        and default values) collected from class-level assignments.
 
     Returns
     -------
@@ -565,6 +627,7 @@ def wrap_docstring(
             fix_rst_backticks=fix_rst_backticks,
             parameter_metadata=function_param_metadata,
             return_annotation=function_return_annotation,
+            attribute_metadata=class_attribute_metadata,
         )
     # Default to NumPy-style for unknown/unspecified styles to be permissive.
     return wrap_docstring_numpy(
@@ -573,5 +636,6 @@ def wrap_docstring(
         leading_indent=leading_indent,
         fix_rst_backticks=fix_rst_backticks,
         parameter_metadata=function_param_metadata,
+        attribute_metadata=class_attribute_metadata,
         return_annotation=function_return_annotation,
     )

{format_docstring-0.2.0 → format_docstring-0.2.2}/format_docstring/line_wrap_google.py

@@ -8,6 +8,7 @@ def wrap_docstring_google(
         fix_rst_backticks: bool = True,
         parameter_metadata: ParameterMetadata | None = None,
         return_annotation: str | None = None,
+        attribute_metadata: ParameterMetadata | None = None,
 ) -> str:
     """A placeholder for now."""  # noqa: D401
     return ''

{format_docstring-0.2.0 → format_docstring-0.2.2}/format_docstring/line_wrap_numpy.py

@@ -19,6 +19,7 @@ def wrap_docstring_numpy(
         leading_indent: int | None = None,
         fix_rst_backticks: bool = False,
         parameter_metadata: ParameterMetadata | None = None,
+        attribute_metadata: ParameterMetadata | None = None,
         return_annotation: str | None = None,
 ) -> str:
     """
@@ -66,12 +67,15 @@ def wrap_docstring_numpy(
         'other parameters:',
         'other parameter',  # tolerate typo
         'other parameter:',
+    }
+    SECTION_ATTRIBUTES = {
         'attributes',
         'attributes:',
         'attribute',  # tolerate typo
         'attribute:',
     }
-    SECTION_RETURNS = {
+    SECTION_SIGNABLE = SECTION_PARAMS | SECTION_ATTRIBUTES
+    SECTION_RETURNS_YIELDS = {
         'returns',
         'returns:',
         'return',  # tolerate typo
@@ -80,6 +84,8 @@ def wrap_docstring_numpy(
         'yields:',
         'yield',  # tolerate typo
         'yield:',
+    }
+    SECTION_RAISES = {
         'raises',
         'raises:',
         'raise',  # tolerate typo
@@ -154,7 +160,11 @@ def wrap_docstring_numpy(
 
         # Parameters-like sections
         section_lower_case: str = current_section.lower()
-        if section_lower_case in SECTION_PARAMS:
+        if section_lower_case in SECTION_SIGNABLE:
+            metadata_for_section = parameter_metadata
+            if section_lower_case in SECTION_ATTRIBUTES:
+                metadata_for_section = attribute_metadata or parameter_metadata
+
             if line.strip() == '':
                 temp_out.append(line)
                 i += 1
@@ -170,7 +180,7 @@ def wrap_docstring_numpy(
                 fixed_line = _fix_colon_spacing(line)
                 fixed_line = _standardize_default_value(fixed_line)
                 fixed_line = _rewrite_parameter_signature(
-                    fixed_line, parameter_metadata
+                    fixed_line, metadata_for_section
                 )
                 fixed_line = _standardize_default_value(fixed_line)
                 temp_out.append(fixed_line)
@@ -183,7 +193,7 @@ def wrap_docstring_numpy(
             continue
 
         # Returns/Yields sections
-        if section_lower_case in SECTION_RETURNS:
+        if section_lower_case in SECTION_RETURNS_YIELDS:
             if line.strip() == '':
                 temp_out.append(line)
                 i += 1
@@ -234,6 +244,19 @@ def wrap_docstring_numpy(
             i += 1
             continue
 
+        # Raises section
+        if section_lower_case in SECTION_RAISES:
+            if line.strip() == '':
+                temp_out.append(line)
+                i += 1
+                continue
+
+            # Treat top-level lines as signatures
+            if indent_length <= leading_indent:  # type: ignore[operator]
+                temp_out.append(line)
+                i += 1
+                continue
+
         # Examples or any other section
         collect_to_temp_output(temp_out, line)
         i += 1

{format_docstring-0.2.0 → format_docstring-0.2.2}/format_docstring.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: format-docstring
-Version: 0.2.0
+Version: 0.2.2
 Summary: A Python formatter to wrap/adjust docstring lines
 Author-email: jsh9 <25124332+jsh9@users.noreply.github.com>
 Maintainer-email: jsh9 <25124332+jsh9@users.noreply.github.com>

{format_docstring-0.2.0 → format_docstring-0.2.2}/format_docstring.egg-info/SOURCES.txt

@@ -58,14 +58,17 @@ tests/test_data/end_to_end/numpy/module_level_docstring.txt
 tests/test_data/end_to_end/numpy/new_lines_before_and_after.txt
 tests/test_data/end_to_end/numpy/no_format_docstring_comment.txt
 tests/test_data/end_to_end/numpy/param_signature_without_type.txt
-tests/test_data/end_to_end/numpy/parameter_signature_sync.txt
 tests/test_data/end_to_end/numpy/parameters_returns_raises_wrapping.txt
 tests/test_data/end_to_end/numpy/returns_signature_and_description.txt
-tests/test_data/end_to_end/numpy/returns_signature_sync.txt
 tests/test_data/end_to_end/numpy/section_headings_with_colons.txt
 tests/test_data/end_to_end/numpy/section_title_fixed.txt
 tests/test_data/end_to_end/numpy/sections_notes_examples.txt
+tests/test_data/end_to_end/numpy/signature_dont_sync_raises.txt
 tests/test_data/end_to_end/numpy/signature_line_is_not_wrapped.txt
+tests/test_data/end_to_end/numpy/signature_sync_class_docstrings.txt
+tests/test_data/end_to_end/numpy/signature_sync_parameters.txt
+tests/test_data/end_to_end/numpy/signature_sync_returns.txt
+tests/test_data/end_to_end/numpy/signature_sync_yields.txt
 tests/test_data/end_to_end/numpy/single_line_docstring.txt
 tests/test_data/end_to_end/numpy/texts_are_rewrapped.txt
 tests/test_data/end_to_end/numpy/very_long_unbreakable_word.txt

{format_docstring-0.2.0 → format_docstring-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "format-docstring"
-version = "0.2.0"
+version = "0.2.2"
 description = "A Python formatter to wrap/adjust docstring lines"
 readme = "README.md"
 license = {text = "MIT"}

{format_docstring-0.2.0 → format_docstring-0.2.2}/tests/test_data/end_to_end/numpy/fix_rst_backticks.txt

@@ -162,7 +162,7 @@ class DataProcessor:
 
     Attributes
     ----------
-    mode : str
+    mode : str, default='standard'
         Processing mode, one of ``'simple'``, ``'standard'``, or
         ``'advanced'``.
     pipelines : list

format_docstring-0.2.2/tests/test_data/end_to_end/numpy/signature_dont_sync_raises.txt

@@ -0,0 +1,48 @@
+LINE_LENGTH: 79
+
+**********
+def func1() -> Any:
+    """
+    Do something.
+
+    This test case is to make sure the raised exceptions are not modified by
+    this formatter.
+
+    Returns
+    -------
+    Any
+
+    Raises
+    ------
+    ValueError
+        When value is wrong. This is a very very very very very very very very very very very very very very very very very very very very very very very very very very very long line.
+    IOError
+        When IO is wrong. This is a very very very very very very very very very very very very very very very very very very very very very very very very very very very long line.
+    """
+    pass
+
+**********
+
+def func1() -> Any:
+    """
+    Do something.
+
+    This test case is to make sure the raised exceptions are not modified by
+    this formatter.
+
+    Returns
+    -------
+    Any
+
+    Raises
+    ------
+    ValueError
+        When value is wrong. This is a very very very very very very very very
+        very very very very very very very very very very very very very very
+        very very very very very long line.
+    IOError
+        When IO is wrong. This is a very very very very very very very very
+        very very very very very very very very very very very very very very
+        very very very very very long line.
+    """
+    pass

format_docstring-0.2.2/tests/test_data/end_to_end/numpy/signature_sync_class_docstrings.txt

@@ -0,0 +1,203 @@
+LINE_LENGTH: 79
+
+**********
+from typing import Callable, Mapping
+
+
+class Widget:
+    """
+    Widget docstring.
+
+    Parameters
+    ----------
+    foo : str
+        Primary value.
+    bar : int
+        Secondary value.
+    options : tuple
+        Additional options payload.
+    callback : Callable
+        Callback invoked after processing.
+    arg_not_in_init_signature    :"MyCustomClassThatHasVeryVeryVeryVeryVeryVeryVeryVeryLongName"
+        Arg
+
+    Attributes
+    ----------
+    qux : dict
+        Class attribute.
+    count : tuple
+        Count attribute.
+    settings : Mapping
+        Settings payload.
+    threshold : float
+        Threshold attribute.
+    prefix : str | None, default='x'
+        Prefix attribute.
+    """
+
+    qux: dict[str, list[int]] = {'alpha': [1, 2]}
+    count: tuple[int, ...]
+    settings: Mapping[str, tuple[int, ...]]
+    threshold: float = 0.75
+    prefix = 'x'  # type: str | None
+
+    def __init__(
+            self,
+            foo: dict[str, list[int]],
+            bar: 'PathLike[str]' | None = None,
+            *,
+            options: tuple[list[int], dict[str, float]] = (
+                [1, 2], {'scale': 0.5}
+            ),
+            callback: Callable[[str, int], bool] | None = None,
+    ) -> None:
+        """Init."""
+        self.foo = foo
+        self.bar = bar
+        self.options = options
+        self.callback = callback
+
+
+class Both:
+    """
+    Both class docstring and __init__
+    docstring will have a Parameters section,
+    and this tool will
+    format the type hints and default values in both
+    docstrings. Even
+    though this is not best
+    practice (and some linters will
+    report an error), it
+    is out of the scope
+    of this
+    formatter
+    to
+    fix
+    this.
+
+    Parameters
+    ----------
+    data:
+        The input data
+    metadata:
+        The metadata
+
+    Attributes
+    ----------
+    something:
+        Something
+    important:
+        Important
+    """
+
+    something: tuple[str, ...] = ['a', 'b', "c", "d"]
+    important: bool = False
+
+    def __init__(self, data: np.ndarray, metadata: dict[str, Any]) -> None:
+        """
+        Initialize the class.
+
+        Parameters
+        ----------
+        data: np.ndarray
+            The input data
+        metadata:
+            The metadata
+        """
+        pass
+
+**********
+from typing import Callable, Mapping
+
+
+class Widget:
+    """
+    Widget docstring.
+
+    Parameters
+    ----------
+    foo : dict[str, list[int]]
+        Primary value.
+    bar : 'PathLike[str]' | None, default=None
+        Secondary value.
+    options : tuple[list[int], dict[str, float]], default=([1, 2], {'scale': 0.5})
+        Additional options payload.
+    callback : Callable[[str, int], bool] | None, default=None
+        Callback invoked after processing.
+    arg_not_in_init_signature : "MyCustomClassThatHasVeryVeryVeryVeryVeryVeryVeryVeryLongName"
+        Arg
+
+    Attributes
+    ----------
+    qux : dict[str, list[int]], default={'alpha': [1, 2]}
+        Class attribute.
+    count : tuple[int, ...]
+        Count attribute.
+    settings : Mapping[str, tuple[int, ...]]
+        Settings payload.
+    threshold : float, default=0.75
+        Threshold attribute.
+    prefix :
+        Prefix attribute.
+    """
+
+    qux: dict[str, list[int]] = {'alpha': [1, 2]}
+    count: tuple[int, ...]
+    settings: Mapping[str, tuple[int, ...]]
+    threshold: float = 0.75
+    prefix = 'x'  # type: str | None
+
+    def __init__(
+            self,
+            foo: dict[str, list[int]],
+            bar: 'PathLike[str]' | None = None,
+            *,
+            options: tuple[list[int], dict[str, float]] = (
+                [1, 2], {'scale': 0.5}
+            ),
+            callback: Callable[[str, int], bool] | None = None,
+    ) -> None:
+        """Init."""
+        self.foo = foo
+        self.bar = bar
+        self.options = options
+        self.callback = callback
+
+
+class Both:
+    """
+    Both class docstring and __init__ docstring will have a Parameters section,
+    and this tool will format the type hints and default values in both
+    docstrings. Even though this is not best practice (and some linters will
+    report an error), it is out of the scope of this formatter to fix this.
+
+    Parameters
+    ----------
+    data : np.ndarray
+        The input data
+    metadata : dict[str, Any]
+        The metadata
+
+    Attributes
+    ----------
+    something : tuple[str, ...], default=['a', 'b', "c", "d"]
+        Something
+    important : bool, default=False
+        Important
+    """
+
+    something: tuple[str, ...] = ['a', 'b', "c", "d"]
+    important: bool = False
+
+    def __init__(self, data: np.ndarray, metadata: dict[str, Any]) -> None:
+        """
+        Initialize the class.
+
+        Parameters
+        ----------
+        data : np.ndarray
+            The input data
+        metadata : dict[str, Any]
+            The metadata
+        """
+        pass

format_docstring-0.2.0/tests/test_data/end_to_end/numpy/parameter_signature_sync.txt → format_docstring-0.2.2/tests/test_data/end_to_end/numpy/signature_sync_parameters.txt

@@ -98,6 +98,37 @@ class Example:
         """
         return flag
 
+
+def docstring_has_inconsistent_args_than_signature(
+        a: int,
+        b: str,
+        c: bool,
+        d: float,
+) -> None:
+    """
+    This
+    docstring has
+    inconsistent arguments
+    than the function signature.
+    This tool will only format the "common
+    args" (args that are in both the docstring
+    and the function signature). Some docstring linters
+    will report an error, but it is out of scope for this tool to deal with this issue.
+
+    Parameters
+    ----------
+    b                   :
+        B
+    d  :
+        D
+    e:
+        E
+    f:
+        F
+    """
+    pass
+
+
 **********
 from typing import List, Optional
 
@@ -195,3 +226,29 @@ class Example:
             Result.
         """
         return flag
+
+
+def docstring_has_inconsistent_args_than_signature(
+        a: int,
+        b: str,
+        c: bool,
+        d: float,
+) -> None:
+    """
+    This docstring has inconsistent arguments than the function signature. This
+    tool will only format the "common args" (args that are in both the
+    docstring and the function signature). Some docstring linters will report
+    an error, but it is out of scope for this tool to deal with this issue.
+
+    Parameters
+    ----------
+    b : str
+        B
+    d : float
+        D
+    e :
+        E
+    f :
+        F
+    """
+    pass

format_docstring-0.2.0/tests/test_data/end_to_end/numpy/returns_signature_sync.txt → format_docstring-0.2.2/tests/test_data/end_to_end/numpy/signature_sync_returns.txt

@@ -84,6 +84,35 @@ def custom_return_type_2() -> tuple['MyType1', "MyType2"]:
     """
     pass
 
+
+def with_return_var_name_1() -> str:
+    """
+    Do something
+
+    Returns
+    -------
+    result:float
+        The result
+    """
+    pass
+
+
+def with_return_var_name_2() -> tuple[str, int, int]:
+    """
+    Do something
+
+    Returns
+    -------
+    name:
+        The name
+    index :bool
+        The index
+    status: str
+        The status
+    """
+    pass
+
+
 **********
 from typing import List
 
@@ -167,3 +196,31 @@ def custom_return_type_2() -> tuple['MyType1', "MyType2"]:
         Integer
     """
     pass
+
+
+def with_return_var_name_1() -> str:
+    """
+    Do something
+
+    Returns
+    -------
+    result : str
+        The result
+    """
+    pass
+
+
+def with_return_var_name_2() -> tuple[str, int, int]:
+    """
+    Do something
+
+    Returns
+    -------
+    name : str
+        The name
+    index : int
+        The index
+    status : int
+        The status
+    """
+    pass

format_docstring-0.2.2/tests/test_data/end_to_end/numpy/signature_sync_yields.txt

@@ -0,0 +1,103 @@
+LINE_LENGTH: 79
+
+**********
+from collections.abc import Generator, Iterator
+
+
+def yield_numbers() -> Iterator[int]:
+    """
+    Yield numbers.
+
+    Yields
+    ------
+    str
+        Should match annotation.
+    """
+    yield 1
+
+
+def yield_named() -> Generator[int, None, None]:
+    """
+    Yield named.
+
+    Yields
+    ------
+    result : str
+        Should match annotation.
+    """
+    yield 1
+
+
+def yield_custom_type_1() -> Iterator['MyType1']:
+    """
+    Yield custom type.
+
+    Yields
+    ------
+    str
+    """
+    yield 'value'
+
+
+def yield_custom_type_2() -> Iterator[tuple['MyType1', "MyType2"]]:
+    """
+    Yield another custom type.
+
+    Yields
+    ------
+    str
+        Combined values.
+    """
+    yield 'value'
+    yield 1
+
+**********
+from collections.abc import Generator, Iterator
+
+
+def yield_numbers() -> Iterator[int]:
+    """
+    Yield numbers.
+
+    Yields
+    ------
+    Iterator[int]
+        Should match annotation.
+    """
+    yield 1
+
+
+def yield_named() -> Generator[int, None, None]:
+    """
+    Yield named.
+
+    Yields
+    ------
+    result : Generator[int, None, None]
+        Should match annotation.
+    """
+    yield 1
+
+
+def yield_custom_type_1() -> Iterator['MyType1']:
+    """
+    Yield custom type.
+
+    Yields
+    ------
+    Iterator['MyType1']
+    """
+    yield 'value'
+
+
+def yield_custom_type_2() -> Iterator[tuple['MyType1', "MyType2"]]:
+    """
+    Yield another custom type.
+
+    Yields
+    ------
+    Iterator[tuple['MyType1', "MyType2"]]
+        Combined values.
+    """
+    yield 'value'
+    yield 1