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

{format_docstring-0.3.0 → format_docstring-0.4.2}/.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.2}/AGENTS.md

@@ -46,6 +46,13 @@ oriented before making changes.
   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.
+- Every prose wrapper goes through
+  `line_wrap_utils.wrap_keeping_inline_literals`, which masks every whitespace
+  character inside rST inline literals (``` ``...`` ```) with a private-use
+  placeholder so each literal wraps as one unbreakable word; breaking inside
+  one would drop significant spaces. `_find_google_signature_colon` likewise
+  skips colons inside inline literals so a literal at the start of a prose line
+  is not mistaken for a signature.
 - Wrapping honors NumPy section heuristics, rST constructs, code fences,
   `Examples` prompts, and literal blocks introduced by `::`.
 - `_normalize_signature_segment` flattens multiline annotations via

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

@@ -6,6 +6,51 @@ 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.2] - 2026-10-04
+
+- Fixed
+  - Line wrapping no longer breaks inside rST inline literals
+    (``` ``...`` ```). Breaking there dropped the whitespace at the break, so a
+    literal such as ``` ``'  '`` ``` lost its spaces. Each inline literal now
+    wraps as one unbreakable word, overflowing like other long words when it is
+    longer than the line. Re-running the formatter rejoins literals that
+    earlier versions split across lines. Tabs and other Unicode whitespace
+    inside a literal are preserved as well, instead of being expanded or
+    collapsed.
+  - Google-style compact first lines no longer collapse runs of spaces inside
+    inline literals.
+  - Google-style prose lines that start with an inline literal containing a
+    colon (such as ``` ``key:value`` ```) are no longer mistaken for signature
+    lines, which rewrote the literal's content on a second pass.
+- Full diff
+  - https://github.com/jsh9/format-docstring/compare/0.4.1...0.4.2
+
+## [0.4.1] - 2026-06-30
+
+- Fixed
+  - Google-style compact docstring wrapping now reserves the opening literal
+    width from the source, so plain triple-quoted summaries keep the correct
+    first-line budget while raw and Unicode prefixes still account for their
+    extra prefix column.
+  - One-character quoted docstring literals and adjacent string-token
+    docstrings are skipped as unsupported formatter targets, so long strings
+    are not wrapped into invalid multi-line source.
+- Full diff
+  - https://github.com/jsh9/format-docstring/compare/0.4.0...0.4.1
+
+## [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.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: format-docstring
-Version: 0.3.0
+Version: 0.4.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>
@@ -53,6 +53,7 @@ ______________________________________________________________________
   - [5.1. Command Line Interface](#51-command-line-interface)
   - [5.2. Pre-commit Hook](#52-pre-commit-hook)
   - [5.3. Opting Out of Formatting](#53-opting-out-of-formatting)
+  - [5.4. What Counts as a Docstring](#54-what-counts-as-a-docstring)
 - [6. Configuration](#6-configuration)
   - [6.1. Command-Line Options](#61-command-line-options)
   - [6.2. Usage Examples](#62-usage-examples)
@@ -68,18 +69,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
@@ -328,6 +328,20 @@ records : list[dict[str, str]]
 """
 ```
 
+**Inline literals are never split.** Each ``` ``...`` ``` span wraps as one
+word, so spaces, tabs and other whitespace inside it are kept and the literal
+stays greppable. A literal longer than the line overflows instead of breaking.
+
+```diff
+"""
+Render a report as text.
+
+-By default, all the nested lines in the generated report are indented with ``'  '`` (two spaces) before they are written.
++By default, all the nested lines in the generated report are indented with
++``'  '`` (two spaces) before they are written.
+"""
+```
+
 **Known sections are parsed, and custom sections are kept.** Recognized section
 titles such as `Parameters`, `Returns`, `Yields`, `Raises`, `Examples`, and
 `Notes` are canonicalized. Unknown underlined sections remain custom sections,
@@ -421,6 +435,20 @@ Args:
 """
 ```
 
+**Inline literals are never split.** Each ``` ``...`` ``` span wraps as one
+word, so spaces, tabs and other whitespace inside it are kept and the literal
+stays greppable. A literal longer than the line overflows instead of breaking.
+
+```diff
+"""
+Render a report as text.
+
+-By default, all the nested lines in the generated report are indented with ``'  '`` (two spaces) before they are written.
++By default, all the nested lines in the generated report are indented with
++``'  '`` (two spaces) before they are written.
+"""
+```
+
 **Custom section boundaries are indentation-sensitive.** Known headers such as
 `Args:`, `Returns:`, `Raises:`, and `Examples:` are canonicalized. Unknown
 peer-level headers after summary content are treated as custom sections, so
@@ -563,26 +591,53 @@ first run `format-docstring`, accept the parts you like, revert the edits you
 dislike, and then add an inline `# no-format-docstring` comment so future runs
 leave that docstring untouched.
 
+### 5.4. What Counts as a Docstring
+
+`format-docstring` follows [Python's docstring rule][python-docstring] to find
+candidate docstrings: the first statement in a module, class, function, or
+method must be a string literal. It intentionally formats only one
+triple-quoted string token with a plain, raw, or Unicode prefix:
+
+```python
+"""Formatted."""
+r"""Formatted."""
+u"""Formatted."""
+```
+
+Single-quoted and double-quoted one-character delimiters can be Python
+docstrings, but they are outside formatter support and are left unchanged.
+Adjacent or implicitly concatenated string literals, formatted string literals,
+and bytes literals are also left unchanged:
+
+```python
+'Not formatted.'
+"Not formatted."
+"""Not formatted.""" "Still not formatted."
+f"""Not a docstring."""
+rf"""Not a docstring."""
+fr"""Not a docstring."""
+b"""Not a docstring."""
+rb"""Not a docstring."""
+br"""Not a docstring."""
+```
+
 ## 6. Configuration
 
 ### 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 +668,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 +688,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 +716,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
@@ -668,4 +749,5 @@ use AI coding assistants to rewrite the docstrings first.
 [black]: https://github.com/psf/black
 [docformatter]: https://github.com/PyCQA/docformatter
 [pydocstringformatter]: https://github.com/DanielNoord/pydocstringformatter
+[python-docstring]: https://docs.python.org/3/glossary.html#term-docstring
 [ruff]: https://github.com/astral-sh/ruff

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

@@ -21,6 +21,7 @@ ______________________________________________________________________
   - [5.1. Command Line Interface](#51-command-line-interface)
   - [5.2. Pre-commit Hook](#52-pre-commit-hook)
   - [5.3. Opting Out of Formatting](#53-opting-out-of-formatting)
+  - [5.4. What Counts as a Docstring](#54-what-counts-as-a-docstring)
 - [6. Configuration](#6-configuration)
   - [6.1. Command-Line Options](#61-command-line-options)
   - [6.2. Usage Examples](#62-usage-examples)
@@ -36,18 +37,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
@@ -296,6 +296,20 @@ records : list[dict[str, str]]
 """
 ```
 
+**Inline literals are never split.** Each ``` ``...`` ``` span wraps as one
+word, so spaces, tabs and other whitespace inside it are kept and the literal
+stays greppable. A literal longer than the line overflows instead of breaking.
+
+```diff
+"""
+Render a report as text.
+
+-By default, all the nested lines in the generated report are indented with ``'  '`` (two spaces) before they are written.
++By default, all the nested lines in the generated report are indented with
++``'  '`` (two spaces) before they are written.
+"""
+```
+
 **Known sections are parsed, and custom sections are kept.** Recognized section
 titles such as `Parameters`, `Returns`, `Yields`, `Raises`, `Examples`, and
 `Notes` are canonicalized. Unknown underlined sections remain custom sections,
@@ -389,6 +403,20 @@ Args:
 """
 ```
 
+**Inline literals are never split.** Each ``` ``...`` ``` span wraps as one
+word, so spaces, tabs and other whitespace inside it are kept and the literal
+stays greppable. A literal longer than the line overflows instead of breaking.
+
+```diff
+"""
+Render a report as text.
+
+-By default, all the nested lines in the generated report are indented with ``'  '`` (two spaces) before they are written.
++By default, all the nested lines in the generated report are indented with
++``'  '`` (two spaces) before they are written.
+"""
+```
+
 **Custom section boundaries are indentation-sensitive.** Known headers such as
 `Args:`, `Returns:`, `Raises:`, and `Examples:` are canonicalized. Unknown
 peer-level headers after summary content are treated as custom sections, so
@@ -531,26 +559,53 @@ first run `format-docstring`, accept the parts you like, revert the edits you
 dislike, and then add an inline `# no-format-docstring` comment so future runs
 leave that docstring untouched.
 
+### 5.4. What Counts as a Docstring
+
+`format-docstring` follows [Python's docstring rule][python-docstring] to find
+candidate docstrings: the first statement in a module, class, function, or
+method must be a string literal. It intentionally formats only one
+triple-quoted string token with a plain, raw, or Unicode prefix:
+
+```python
+"""Formatted."""
+r"""Formatted."""
+u"""Formatted."""
+```
+
+Single-quoted and double-quoted one-character delimiters can be Python
+docstrings, but they are outside formatter support and are left unchanged.
+Adjacent or implicitly concatenated string literals, formatted string literals,
+and bytes literals are also left unchanged:
+
+```python
+'Not formatted.'
+"Not formatted."
+"""Not formatted.""" "Still not formatted."
+f"""Not a docstring."""
+rf"""Not a docstring."""
+fr"""Not a docstring."""
+b"""Not a docstring."""
+rb"""Not a docstring."""
+br"""Not a docstring."""
+```
+
 ## 6. Configuration
 
 ### 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 +636,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 +656,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 +684,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
@@ -636,4 +717,5 @@ use AI coding assistants to rewrite the docstrings first.
 [black]: https://github.com/psf/black
 [docformatter]: https://github.com/PyCQA/docformatter
 [pydocstringformatter]: https://github.com/DanielNoord/pydocstringformatter
+[python-docstring]: https://docs.python.org/3/glossary.html#term-docstring
 [ruff]: https://github.com/astral-sh/ruff