Skip to content

fix: preserve inline comments on skipped docstrings - #412

Draft
Dodothereal wants to merge 1 commit into
PyCQA:masterfrom
Dodothereal:fix/skipped-docstring-inline-comments-20261102
Draft

Dodothereal wants to merge 1 commit into
PyCQA:masterfrom
Dodothereal:fix/skipped-docstring-inline-comments-20261102

Conversation

@Dodothereal

@Dodothereal Dodothereal commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor

A docstring excluded by --range or --docstring-length can still crash when an inline comment follows it. For example, """doc.""" # noqa: D400 with --range 20 30 raises ValueError: start (1,12) precedes previous end (2,0).

The unformatted-docstring path was inserting a synthetic newline before the existing comment. Pass the following token into that path and leave the comment and its newline in their original order.

This adds 364 regression parameter combinations covering range and length exclusions, --black, LF/CRLF, EOF with or without a final newline, several docstring contexts, unchanged content, idempotence, and continued formatting of another selected docstring. The existing helper test is updated for the new argument.

Validation history:

  • November 2, 2026 (Python 3.12.14): Initial focused validation on candidate head e52e172210ed0d2da1e5ed2a0bf2c3718ab3c72e. 364 new regression cases and 180 existing test cases passed in a module-level harness, plus 2,914 additional independent regression permutations.
  • November 6, 2026 (Python 3.12.13): Local pytest validation conducted in an isolated virtual environment (uv, dedicated venv, editable install docformatter==1.7.8 verified from src/docformatter/__init__.py, VIRTUAL_ENV set for CLI entry point tests):
    • Head (e52e172210ed0d2da1e5ed2a0bf2c3718ab3c72e):
      • Full pytest suite: 1,156 passed, 3 skipped (1,159 total collected items in 1.97s).
      • tests/formatter/test_skipped_docstring_comments.py: 364 passed, 0 failed (0.23s).
      • CLI & configuration tests (test_docformatter.py, test_configuration_functions.py via legitimate entry point): 95 passed, 0 failed (1.13s).
    • Baseline comparison against clean base (2a6f2742fee1fa14dc38587b1d34cd81519fb2d4):
      • Full pytest suite: 792 passed, 3 skipped (795 total collected items in 1.73s).
      • tests/formatter/test_skipped_docstring_comments.py: 284 failed, 80 passed (failing with ValueError: start precedes previous end when an inline comment follows a skipped docstring; note that 80 cases pass on baseline where comments/tokens did not trigger the collision).
    • Note: Multi-interpreter matrix via tox (py310, py311, py313, py314, pypy3) and pre-commit hooks were not run in this local follow-up validation. GitHub Actions test matrix (6 test jobs across supported versions + lint) is all-green on this commit.

AI Assistance Disclosure:

  • Initial implementation and initial test generation: OpenAI assistance.
  • Follow-up testing, baseline reproduction, isolated venv validation, and documentation updates: Gemini / T3 Code assistance.

Related to #346, but this addresses the skipped-docstring path rather than the already-fixed formatted-docstring case.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant