format-docstring 0.3.0__tar.gz → 0.4.0__tar.gz

{format_docstring-0.3.0 → format_docstring-0.4.0}/.pre-commit-config.yaml

@@ -17,7 +17,7 @@ repos:
         exclude: ^tests/helpers\.py$
       - id: check-merge-conflict
   - repo: https://github.com/jsh9/muff-pre-commit
-    rev: 0.13.2
+    rev: 0.15.20
     hooks:
       - id: muff-format
         args: [--config, muff.toml]
@@ -27,11 +27,11 @@ repos:
       - id: blank-line-after-blocks
       - id: blank-line-after-blocks-jupyter
   - repo: https://github.com/lyz-code/yamlfix
-    rev: 1.18.0
+    rev: 1.19.1
     hooks:
       - id: yamlfix
   - repo: https://github.com/pappasam/toml-sort
-    rev: v0.24.2
+    rev: v0.24.4
     hooks:
       - id: toml-sort-fix
         args:
@@ -42,7 +42,7 @@ repos:
           - --trailing-comma-inline-array
           - --sort-inline-arrays
   - repo: https://github.com/macisamuele/language-formatters-pre-commit-hooks
-    rev: v2.15.0
+    rev: v2.16.0
     hooks:
       - id: pretty-format-ini
         args: [--autofix]
@@ -63,15 +63,28 @@ repos:
           - --no-sort-keys
           - --no-eof-newline
   - repo: https://github.com/jsh9/markdown-toc-creator
-    rev: 0.1.0
+    rev: 0.1.3
     hooks:
       - id: markdown-toc-creator
         exclude: ^AGENTS\.md$|^CHANGELOG\.md$
   - repo: https://github.com/jsh9/markdown-heading-numbering
-    rev: 0.1.0
+    rev: 0.1.1
     hooks:
       - id: markdown-heading-numbering
         exclude: ^CHANGELOG\.md$
+  - repo: https://github.com/jsh9/pre-commit-tox-version-sync
+    rev: 0.1.1
+    hooks:
+      - id: sync-precommit-tox-versions
+        args:
+          - --pre-commit-repo
+          - https://github.com/jsh9/muff-pre-commit
+          - --tox-env
+          - muff-lint
+          - --tox-env
+          - muff-format
+          - --tox-dep
+          - muff
   - repo: local
     hooks:
       - id: format-docstring

{format_docstring-0.3.0 → format_docstring-0.4.0}/CHANGELOG.md

@@ -6,6 +6,19 @@ 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.4.0] - 2026-06-29
+
+- Added
+  - CLI and `pyproject.toml` options to control whether argument types,
+    argument defaults, and Google return/yield types are included in docstring
+    signature lines for Python files and Jupyter notebooks.
+- Fixed
+  - Google-style argument signature synchronization preserves existing
+    `required` metadata when source annotations replace stale docstring type
+    text.
+- Full diff
+  - https://github.com/jsh9/format-docstring/compare/0.3.0...0.4.0
+
 ## [0.3.0] - 2026-06-19
 
 - Added

{format_docstring-0.3.0 → format_docstring-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: format-docstring
-Version: 0.3.0
+Version: 0.4.0
 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>
@@ -68,18 +68,17 @@ ______________________________________________________________________
 `format-docstring` is a tool that automatically formats and wraps docstring
 content in Python files and Jupyter notebooks.
 
-Baseline reflow corresponds to the common docstring cleanups offered by
-general-purpose formatters: splitting one-line docstrings into the canonical
-multi-line layout (triple quotes, blank line, summary), normalizing
-indentation, and wrapping text at a fixed column width without applying extra
-heuristics.
-
 | Feature                                   | `format-docstring` | [docformatter] | [pydocstringformatter] | [Ruff] | [Black] |
 | ----------------------------------------- | ------------------ | -------------- | ---------------------- | ------ | ------- |
 | Docstring wrapping                        | ✅                 | ❌             | ❌                     | ❌     | ❌      |
 | Compatible with line length linter (E501) | ✅                 | ❌             | ❌                     | N/A    | N/A     |
 | Fixes common docstring typos              | ✅                 | ❌             | ❌                     | ❌     | ❌      |
 
+For stronger docstring checks, use `format-docstring` together with
+[`pydoclint`](https://github.com/jsh9/pydoclint). `format-docstring` handles
+formatting and wrapping, while `pydoclint` checks docstring completeness and
+consistency with function signatures.
+
 ## 2. Before vs After Examples
 
 These examples show the same kinds of cleanup in the two supported docstring
@@ -567,22 +566,19 @@ leave that docstring untouched.
 
 ### 6.1. Command-Line Options
 
-- `--line-length INTEGER`: Maximum line length for wrapping docstrings
-  (default: 79)
-- `--docstring-style CHOICE`: Docstring style to target (`numpy` or `google`,
-  default: `numpy`). This selects the style to format, not a converter between
-  styles.
-- `--fix-rst-backticks BOOL`: Automatically fix single backticks to double
-  backticks per rST syntax (default: `True`). Pass `False` to disable this.
-- `--verbose CHOICE`: Logging detail level (`default` keeps the existing
-  behaviour, `diff` prints unified diffs when rewrites happen)
-- `--exclude TEXT`: Regex pattern to exclude files/directories (default:
-  `\.git|\.tox|\.pytest_cache`)
-- `--config PATH`: Path to a `pyproject.toml` config file. If not specified,
-  the tool automatically searches for `pyproject.toml` in parent directories.
-  Command-line options take precedence over config file settings.
-- `--version`: Show version information
-- `--help`: Show help message
+| Option                                  | Default                        | Description                                                                                                                                                                                           |
+| --------------------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--line-length INTEGER`                 | `79`                           | Maximum line length for wrapping docstrings.                                                                                                                                                          |
+| `--docstring-style CHOICE`              | `numpy`                        | Docstring style to target, either `numpy` or `google`. This selects the style to format, not a converter between styles.                                                                              |
+| `--fix-rst-backticks BOOL`              | `True`                         | Automatically fix single backticks to double backticks per rST syntax. Pass `False` to disable this.                                                                                                  |
+| `--include-arg-types BOOL`              | `True`                         | Include argument type hints in parameter docstrings. Pass `False` to remove them from structured arg and attribute signature lines; defaults must also be disabled.                                   |
+| `--include-arg-defaults BOOL`           | `True`                         | Include argument defaults in parameter docstrings. Pass `False` to remove explicit defaults and `optional` markers from structured arg and attribute signature lines. Requires argument types.        |
+| `--include-return-and-yield-types BOOL` | `True`                         | Include type hints in `Returns` and `Yields` docstrings. Pass `False` to remove them from Google-style return/yield descriptions. NumPy style does not allow `False`.                                 |
+| `--verbose CHOICE`                      | `default`                      | Logging detail level. `default` keeps the existing behaviour; `diff` prints unified diffs when rewrites happen.                                                                                       |
+| `--exclude TEXT`                        | `\.git\|\.tox\|\.pytest_cache` | Regex pattern to exclude files/directories.                                                                                                                                                           |
+| `--config PATH`                         | None                           | Path to a `pyproject.toml` config file. If not specified, the tool automatically searches for `pyproject.toml` in parent directories. Command-line options take precedence over config file settings. |
+| `--version`                             | N/A                            | Show version information.                                                                                                                                                                             |
+| `--help`                                | N/A                            | Show help message.                                                                                                                                                                                    |
 
 ### 6.2. Usage Examples
 
@@ -613,6 +609,12 @@ format-docstring --config pyproject.toml --line-length 100 src/
 
 # Disable backtick fixing
 format-docstring --fix-rst-backticks=False my_module.py
+
+# Omit argument defaults, including optional markers
+format-docstring --include-arg-defaults=False src/
+
+# Omit Google-style return/yield type text when annotations carry the types
+format-docstring --docstring-style google --include-return-and-yield-types=False src/
 ```
 
 ### 6.3. `pyproject.toml` Configuration
@@ -627,17 +629,24 @@ as `line-length`.
 line_length = 79
 docstring_style = "numpy"
 fix_rst_backticks = true
+include_arg_types = true
+include_arg_defaults = true
+include_return_and_yield_types = true
 exclude = "\\.git|\\.venv|__pycache__"
 verbose = "default"  # or "diff" to print unified diffs
 ```
 
-For Google-style docstrings:
+For Google-style docstrings that omit argument types/defaults and return/yield
+types:
 
 ```toml
 [tool.format_docstring]
 docstring_style = "google"
 line_length = 79
 fix_rst_backticks = true
+include_arg_types = false
+include_arg_defaults = false
+include_return_and_yield_types = false
 ```
 
 **Available options:**
@@ -648,6 +657,19 @@ fix_rst_backticks = true
   `"numpy"` or `"google"`. Default: `"numpy"`.
 - `fix_rst_backticks` / `fix-rst-backticks` (bool): whether to convert single
   backticks in prose to double backticks per rST syntax. Default: `true`.
+- `include_arg_types` / `include-arg-types` (bool): whether to include argument
+  type hints in parameter docstrings. Default: `true`. If this is `false`,
+  `include_arg_defaults` must also be `false`.
+- `include_arg_defaults` / `include-arg-defaults` (bool): whether to include
+  argument defaults in parameter docstrings. Default: `true`. This requires
+  `include_arg_types = true`. When set to `false`, explicit defaults and
+  `optional` markers are removed from structured signatures, including compact
+  or extra-spaced forms such as `,optional` and `,   optional`. For example,
+  `x : int, optional` becomes `x : int` and `x (int, optional):` becomes
+  `x (int):`.
+- `include_return_and_yield_types` / `include-return-and-yield-types` (bool):
+  whether to include return and yield type hints in docstrings. Default:
+  `true`. Setting this to `false` is supported only with Google style.
 - `exclude` (str): regex pattern used to skip files or directories. Default:
   `"\\.git|\\.tox|\\.pytest_cache"`.
 - `verbose` (str): logging detail level, either `"default"` or `"diff"`. Use

{format_docstring-0.3.0 → format_docstring-0.4.0}/README.md

@@ -36,18 +36,17 @@ ______________________________________________________________________
 `format-docstring` is a tool that automatically formats and wraps docstring
 content in Python files and Jupyter notebooks.
 
-Baseline reflow corresponds to the common docstring cleanups offered by
-general-purpose formatters: splitting one-line docstrings into the canonical
-multi-line layout (triple quotes, blank line, summary), normalizing
-indentation, and wrapping text at a fixed column width without applying extra
-heuristics.
-
 | Feature                                   | `format-docstring` | [docformatter] | [pydocstringformatter] | [Ruff] | [Black] |
 | ----------------------------------------- | ------------------ | -------------- | ---------------------- | ------ | ------- |
 | Docstring wrapping                        | ✅                 | ❌             | ❌                     | ❌     | ❌      |
 | Compatible with line length linter (E501) | ✅                 | ❌             | ❌                     | N/A    | N/A     |
 | Fixes common docstring typos              | ✅                 | ❌             | ❌                     | ❌     | ❌      |
 
+For stronger docstring checks, use `format-docstring` together with
+[`pydoclint`](https://github.com/jsh9/pydoclint). `format-docstring` handles
+formatting and wrapping, while `pydoclint` checks docstring completeness and
+consistency with function signatures.
+
 ## 2. Before vs After Examples
 
 These examples show the same kinds of cleanup in the two supported docstring
@@ -535,22 +534,19 @@ leave that docstring untouched.
 
 ### 6.1. Command-Line Options
 
-- `--line-length INTEGER`: Maximum line length for wrapping docstrings
-  (default: 79)
-- `--docstring-style CHOICE`: Docstring style to target (`numpy` or `google`,
-  default: `numpy`). This selects the style to format, not a converter between
-  styles.
-- `--fix-rst-backticks BOOL`: Automatically fix single backticks to double
-  backticks per rST syntax (default: `True`). Pass `False` to disable this.
-- `--verbose CHOICE`: Logging detail level (`default` keeps the existing
-  behaviour, `diff` prints unified diffs when rewrites happen)
-- `--exclude TEXT`: Regex pattern to exclude files/directories (default:
-  `\.git|\.tox|\.pytest_cache`)
-- `--config PATH`: Path to a `pyproject.toml` config file. If not specified,
-  the tool automatically searches for `pyproject.toml` in parent directories.
-  Command-line options take precedence over config file settings.
-- `--version`: Show version information
-- `--help`: Show help message
+| Option                                  | Default                        | Description                                                                                                                                                                                           |
+| --------------------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--line-length INTEGER`                 | `79`                           | Maximum line length for wrapping docstrings.                                                                                                                                                          |
+| `--docstring-style CHOICE`              | `numpy`                        | Docstring style to target, either `numpy` or `google`. This selects the style to format, not a converter between styles.                                                                              |
+| `--fix-rst-backticks BOOL`              | `True`                         | Automatically fix single backticks to double backticks per rST syntax. Pass `False` to disable this.                                                                                                  |
+| `--include-arg-types BOOL`              | `True`                         | Include argument type hints in parameter docstrings. Pass `False` to remove them from structured arg and attribute signature lines; defaults must also be disabled.                                   |
+| `--include-arg-defaults BOOL`           | `True`                         | Include argument defaults in parameter docstrings. Pass `False` to remove explicit defaults and `optional` markers from structured arg and attribute signature lines. Requires argument types.        |
+| `--include-return-and-yield-types BOOL` | `True`                         | Include type hints in `Returns` and `Yields` docstrings. Pass `False` to remove them from Google-style return/yield descriptions. NumPy style does not allow `False`.                                 |
+| `--verbose CHOICE`                      | `default`                      | Logging detail level. `default` keeps the existing behaviour; `diff` prints unified diffs when rewrites happen.                                                                                       |
+| `--exclude TEXT`                        | `\.git\|\.tox\|\.pytest_cache` | Regex pattern to exclude files/directories.                                                                                                                                                           |
+| `--config PATH`                         | None                           | Path to a `pyproject.toml` config file. If not specified, the tool automatically searches for `pyproject.toml` in parent directories. Command-line options take precedence over config file settings. |
+| `--version`                             | N/A                            | Show version information.                                                                                                                                                                             |
+| `--help`                                | N/A                            | Show help message.                                                                                                                                                                                    |
 
 ### 6.2. Usage Examples
 
@@ -581,6 +577,12 @@ format-docstring --config pyproject.toml --line-length 100 src/
 
 # Disable backtick fixing
 format-docstring --fix-rst-backticks=False my_module.py
+
+# Omit argument defaults, including optional markers
+format-docstring --include-arg-defaults=False src/
+
+# Omit Google-style return/yield type text when annotations carry the types
+format-docstring --docstring-style google --include-return-and-yield-types=False src/
 ```
 
 ### 6.3. `pyproject.toml` Configuration
@@ -595,17 +597,24 @@ as `line-length`.
 line_length = 79
 docstring_style = "numpy"
 fix_rst_backticks = true
+include_arg_types = true
+include_arg_defaults = true
+include_return_and_yield_types = true
 exclude = "\\.git|\\.venv|__pycache__"
 verbose = "default"  # or "diff" to print unified diffs
 ```
 
-For Google-style docstrings:
+For Google-style docstrings that omit argument types/defaults and return/yield
+types:
 
 ```toml
 [tool.format_docstring]
 docstring_style = "google"
 line_length = 79
 fix_rst_backticks = true
+include_arg_types = false
+include_arg_defaults = false
+include_return_and_yield_types = false
 ```
 
 **Available options:**
@@ -616,6 +625,19 @@ fix_rst_backticks = true
   `"numpy"` or `"google"`. Default: `"numpy"`.
 - `fix_rst_backticks` / `fix-rst-backticks` (bool): whether to convert single
   backticks in prose to double backticks per rST syntax. Default: `true`.
+- `include_arg_types` / `include-arg-types` (bool): whether to include argument
+  type hints in parameter docstrings. Default: `true`. If this is `false`,
+  `include_arg_defaults` must also be `false`.
+- `include_arg_defaults` / `include-arg-defaults` (bool): whether to include
+  argument defaults in parameter docstrings. Default: `true`. This requires
+  `include_arg_types = true`. When set to `false`, explicit defaults and
+  `optional` markers are removed from structured signatures, including compact
+  or extra-spaced forms such as `,optional` and `,   optional`. For example,
+  `x : int, optional` becomes `x : int` and `x (int, optional):` becomes
+  `x (int):`.
+- `include_return_and_yield_types` / `include-return-and-yield-types` (bool):
+  whether to include return and yield type hints in docstrings. Default:
+  `true`. Setting this to `false` is supported only with Google style.
 - `exclude` (str): regex pattern used to skip files or directories. Default:
   `"\\.git|\\.tox|\\.pytest_cache"`.
 - `verbose` (str): logging detail level, either `"default"` or `"diff"`. Use

{format_docstring-0.3.0 → format_docstring-0.4.0}/format_docstring/config.py

@@ -19,6 +19,9 @@ _VALUE_OPTIONS = frozenset({
     '--docstring-style',
     '--exclude',
     '--fix-rst-backticks',
+    '--include-arg-defaults',
+    '--include-arg-types',
+    '--include-return-and-yield-types',
     '--line-length',
     '--verbose',
 })
@@ -51,6 +54,108 @@ class ConfigFileCommand(click.Command):
         return super().parse_args(ctx, args)
 
 
+def validate_cli_include_options(
+        docstring_style: str,
+        *,
+        include_arg_types: bool,
+        include_arg_defaults: bool,
+        include_return_and_yield_types: bool,
+) -> None:
+    """
+    Validate cross-option rules for Click entrypoints.
+
+    This runs before fixer construction so invalid CLI/config combinations fail
+    before a multi-path invocation can rewrite any files or notebooks.
+
+    Parameters
+    ----------
+    docstring_style : str
+        The selected docstring style.
+    include_arg_types : bool
+        Whether argument type hints should be included in docstrings.
+    include_arg_defaults : bool
+        Whether argument defaults should be included in docstrings.
+    include_return_and_yield_types : bool
+        Whether return and yield type hints should be included in docstrings.
+    """
+    validate_cli_include_arg_defaults(
+        include_arg_types=include_arg_types,
+        include_arg_defaults=include_arg_defaults,
+    )
+    validate_cli_include_return_and_yield_types(
+        docstring_style,
+        include_return_and_yield_types=include_return_and_yield_types,
+    )
+
+
+def validate_cli_include_arg_defaults(
+        *,
+        include_arg_types: bool,
+        include_arg_defaults: bool,
+) -> None:
+    """
+    Validate argument defaults are not emitted without argument types.
+
+    Defaults are rendered inside the same signature slot as types, so allowing
+    defaults alone would produce non-standard lines such as ``arg : default=3``
+    or ``arg (default=3):``.
+
+    Parameters
+    ----------
+    include_arg_types : bool
+        Whether argument type hints should be included in docstrings.
+    include_arg_defaults : bool
+        Whether argument defaults should be included in docstrings.
+
+    Raises
+    ------
+    click.UsageError
+        If defaults are requested while argument types are omitted.
+    """
+    if include_arg_types or not include_arg_defaults:
+        return
+
+    msg = (
+        '--include-arg-defaults=True requires --include-arg-types=True. '
+        'Set --include-arg-defaults=False when omitting argument types.'
+    )
+    raise click.UsageError(msg)
+
+
+def validate_cli_include_return_and_yield_types(
+        docstring_style: str,
+        *,
+        include_return_and_yield_types: bool,
+) -> None:
+    """
+    Validate return/yield type suppression for Click entrypoints.
+
+    Parameters
+    ----------
+    docstring_style : str
+        The selected docstring style.
+    include_return_and_yield_types : bool
+        Whether return and yield type hints should be included in docstrings.
+
+    Raises
+    ------
+    click.UsageError
+        If return/yield type suppression is requested for NumPy docstrings.
+    """
+    if (
+        include_return_and_yield_types
+        or docstring_style.strip().lower() != 'numpy'
+    ):
+        return
+
+    msg = (
+        '--include-return-and-yield-types=False is only supported for '
+        'Google-style docstrings because NumPy/numpydoc requires return '
+        'and yield type lines.'
+    )
+    raise click.UsageError(msg)
+
+
 def _find_config_for_raw_args(args: list[str]) -> Path | None:
     """
     Resolve the config file implied by raw CLI arguments.

{format_docstring-0.3.0 → format_docstring-0.4.0}/format_docstring/docstring_rewriter.py

@@ -12,6 +12,7 @@ from format_docstring.line_wrap_numpy import (
     handle_single_line_docstring,
     wrap_docstring_numpy,
 )
+from format_docstring.line_wrap_utils import validate_include_arg_defaults
 
 if TYPE_CHECKING:
     from format_docstring.line_wrap_utils import ParameterMetadata
@@ -309,6 +310,9 @@ def fix_src(
         line_length: int = 79,
         docstring_style: str = 'numpy',
         fix_rst_backticks: bool = True,
+        include_arg_types: bool = True,
+        include_arg_defaults: bool = True,
+        include_return_and_yield_types: bool = True,
 ) -> str:
     """
     Return code with only docstrings updated to wrapped content.
@@ -324,6 +328,13 @@ def fix_src(
     fix_rst_backticks : bool, default=True
         If True, automatically fix single backticks to double backticks per rST
         syntax.
+    include_arg_types : bool, default=True
+        If True, include argument type hints in parameter docstrings.
+    include_arg_defaults : bool, default=True
+        If True, include argument defaults in parameter docstrings.
+    include_return_and_yield_types : bool, default=True
+        If True, include return and yield type hints in docstrings. This can
+        only be disabled for Google-style docstrings.
 
     Returns
     -------
@@ -337,6 +348,12 @@ def fix_src(
     spans directly in the original text to preserve non-docstring formatting
     and comments.
     """
+    _validate_include_options(
+        docstring_style,
+        include_arg_types=include_arg_types,
+        include_arg_defaults=include_arg_defaults,
+        include_return_and_yield_types=include_return_and_yield_types,
+    )
     tree: ast.Module = ast.parse(source_code, type_comments=True)
     line_starts: list[int] = calc_line_starts(source_code)
 
@@ -351,6 +368,9 @@ def fix_src(
         line_length=line_length,
         docstring_style=docstring_style,
         fix_rst_backticks=fix_rst_backticks,
+        include_arg_types=include_arg_types,
+        include_arg_defaults=include_arg_defaults,
+        include_return_and_yield_types=include_return_and_yield_types,
     )
     if replacement is not None:
         replacements.append(replacement)
@@ -367,6 +387,9 @@ def fix_src(
                 line_length=line_length,
                 docstring_style=docstring_style,
                 fix_rst_backticks=fix_rst_backticks,
+                include_arg_types=include_arg_types,
+                include_arg_defaults=include_arg_defaults,
+                include_return_and_yield_types=include_return_and_yield_types,
             )
             if replacement is not None:
                 replacements.append(replacement)
@@ -414,6 +437,9 @@ def build_replacement_docstring(
         line_length: int,
         docstring_style: str = 'numpy',
         fix_rst_backticks: bool = True,
+        include_arg_types: bool = True,
+        include_arg_defaults: bool = True,
+        include_return_and_yield_types: bool = True,
 ) -> tuple[int, int, str] | None:
     """
     Compute a single docstring replacement for the given node.
@@ -433,6 +459,13 @@ def build_replacement_docstring(
     fix_rst_backticks : bool, default=True
         If True, automatically fix single backticks to double backticks per rST
         syntax.
+    include_arg_types : bool, default=True
+        If True, include argument type hints in parameter docstrings.
+    include_arg_defaults : bool, default=True
+        If True, include argument defaults in parameter docstrings.
+    include_return_and_yield_types : bool, default=True
+        If True, include return and yield type hints in docstrings. This can
+        only be disabled for Google-style docstrings.
 
     Returns
     -------
@@ -532,6 +565,9 @@ def build_replacement_docstring(
         function_param_metadata=param_metadata,
         function_return_annotation=return_annotation,
         class_attribute_metadata=attribute_metadata,
+        include_arg_types=include_arg_types,
+        include_arg_defaults=include_arg_defaults,
+        include_return_and_yield_types=include_return_and_yield_types,
         compact_google_docstring=True,
         append_google_closing_indent=True,
     )
@@ -686,6 +722,9 @@ def wrap_docstring(
         function_param_metadata: ParameterMetadata | None = None,
         function_return_annotation: str | None = None,
         class_attribute_metadata: ParameterMetadata | None = None,
+        include_arg_types: bool = True,
+        include_arg_defaults: bool = True,
+        include_return_and_yield_types: bool = True,
         compact_google_docstring: bool = False,
         append_google_closing_indent: bool = False,
 ) -> str:
@@ -716,6 +755,13 @@ def wrap_docstring(
     class_attribute_metadata : ParameterMetadata | None, default=None
         Attribute metadata for class docstrings (names mapped to annotations
         and default values) collected from class-level assignments.
+    include_arg_types : bool, default=True
+        If True, include argument type hints in parameter docstrings.
+    include_arg_defaults : bool, default=True
+        If True, include argument defaults in parameter docstrings.
+    include_return_and_yield_types : bool, default=True
+        If True, include return and yield type hints in docstrings. This can
+        only be disabled for Google-style docstrings.
     compact_google_docstring : bool, default=False
         If True, Google-style wrapping may place the first summary line beside
         the opening quotes when indentation allows it.
@@ -735,6 +781,12 @@ def wrap_docstring(
     - 'google' -> wrap_docstring_google
     """
     style = (docstring_style or '').strip().lower()
+    _validate_include_options(
+        style,
+        include_arg_types=include_arg_types,
+        include_arg_defaults=include_arg_defaults,
+        include_return_and_yield_types=include_return_and_yield_types,
+    )
     # Normalize once so style-specific code can preserve the difference between
     # omitted indentation, explicit module-level zero, and explicit ``None``.
     leading_indent_was_unset = leading_indent is _LEADING_INDENT_UNSET
@@ -761,6 +813,9 @@ def wrap_docstring(
             parameter_metadata=function_param_metadata,
             return_annotation=function_return_annotation,
             attribute_metadata=class_attribute_metadata,
+            include_arg_types=include_arg_types,
+            include_arg_defaults=include_arg_defaults,
+            include_return_and_yield_types=include_return_and_yield_types,
             compact_first_line=compact_google_docstring,
         )
     # Default to NumPy-style for unknown/unspecified styles to be permissive.
@@ -775,4 +830,55 @@ def wrap_docstring(
         parameter_metadata=function_param_metadata,
         attribute_metadata=class_attribute_metadata,
         return_annotation=function_return_annotation,
+        include_arg_types=include_arg_types,
+        include_arg_defaults=include_arg_defaults,
+        include_return_and_yield_types=include_return_and_yield_types,
+    )
+
+
+def _validate_include_options(
+        docstring_style: str,
+        *,
+        include_arg_types: bool,
+        include_arg_defaults: bool,
+        include_return_and_yield_types: bool,
+) -> None:
+    """
+    Validate cross-option rules for direct formatter API calls.
+
+    CLI entrypoints validate before constructing fixers, but library callers
+    can call ``fix_src`` or ``wrap_docstring`` directly. Keep the same option
+    contract at this boundary before any wrapping logic can run.
+    """
+    validate_include_arg_defaults(
+        include_arg_types=include_arg_types,
+        include_arg_defaults=include_arg_defaults,
+    )
+    _validate_include_return_and_yield_types(
+        docstring_style,
+        include_return_and_yield_types=include_return_and_yield_types,
+    )
+
+
+def _validate_include_return_and_yield_types(
+        docstring_style: str,
+        *,
+        include_return_and_yield_types: bool,
+) -> None:
+    """
+    Validate return/yield type suppression is only used for Google style.
+
+    CLI entrypoints check this before touching files, but direct API callers
+    can bypass Click; this keeps the formatter's public API aligned with the
+    same numpydoc strictness rule.
+    """
+    style = (docstring_style or '').strip().lower()
+    if include_return_and_yield_types or style == 'google':
+        return
+
+    msg = (
+        'include_return_and_yield_types=False is only supported for '
+        'Google-style docstrings because NumPy/numpydoc requires return and '
+        'yield type lines.'
     )
+    raise ValueError(msg)