chore: add docstring formatting + linting - #1567
Open
WilliamBergamin wants to merge 4 commits into
Open
Conversation
Enable Ruff's pydocstyle `D` rules with the google convention and `docstring-code-format`, and fix every resulting violation on docstrings that already exist across slack_bolt/ and examples/. - pyproject.toml: select "D" (google convention); ignore only the missing-docstring rules D100-D107 so no docstrings are invented where none exist; enable docstring-code-format. - Fix all D2xx/D4xx violations on existing docstrings (D205 blank line after summary, D415 terminal punctuation, D417 undocumented params, and safe structural fixes). No docstrings added. - scripts/format.sh: format examples/ too. - scripts/lint.sh: add `ruff format --check` gate so local matches CI. Sync/async docstring pairs updated symmetrically. Co-Authored-By: Claude <svc-devxp-claude@slack-corp.com>
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #1567 +/- ##
=======================================
Coverage 91.54% 91.54%
=======================================
Files 228 228
Lines 7285 7285
=======================================
Hits 6669 6669
Misses 616 616 ☔ View full report in Codecov by Harness. |
WilliamBergamin
changed the title
The ruff pydocstyle (D) reformatting enforced docstring shape but not content, leaving six correctness/consistency defects: - falcon/resource.py: reformatting turned the usage snippet into an invalid example (`app = App().`); restore a proper summary + clean code - socket_mode base_handler.py / async_base_handler.py: summary split mid sentence left a dangling lowercase fragment; merge it back - __init__.py: "features.Read" was missing a space (shown on PyPI) - async_app.py dialog_cancellation: summary wrongly said dialog_submission - app.py / async_app.py step(): de-indent the orphaned Deprecated block - async_authorize.py: add backticks around `authorize` to mirror the sync CallableAuthorize docstring Docstring-only; no behavior change. Sync/async pairs kept mirrored. Co-Authored-By: Claude <svc-devxp-claude@slack-corp.com>
Drop the restatement of what the google convention does (discoverable in ruff's docs) and keep only the non-obvious footgun: switching the bare `select = ["D"]` category to explicit D codes overrides the convention. Co-Authored-By: Claude <svc-devxp-claude@slack-corp.com>
The listed 07e8ac9 was the pre-squash branch commit from PR #1566; that SHA is unreachable from main, so git blame silently ignored the entry. Point it at the squash-merge commit 5814077, which is the reachable commit that actually carried the ruff-format sweep onto main. Co-Authored-By: Claude <svc-devxp-claude@slack-corp.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds docstring formatting + linting via Ruff's pydocstyle (
D) rules, fixing violations rather than suppressing them.Config (
pyproject.toml):select = ["E", "W", "F", "D"]with[tool.ruff.lint.pydocstyle] convention = "google".Drules ignored are the missing-docstring ones (D100–D107)Drule fires only on existing docstrings.[tool.ruff.format] docstring-code-format = true(forward-looking; no-op on current code).Fixes:
D205blank line after summary,D415terminal punctuation,D417undocumented params, plus safe structural fixes (D212,D209,D202, etc.).step.py/async_step.py,request_verification.py/async_request_verification.py).# noqaor per-file-ignores added.Scripts / CI gate:
scripts/format.shnow formatsexamples/too.scripts/lint.shaddsruff format --check slack_bolt/ tests/ examples/so local matches CITesting
ruff check slack_bolt/ examples/→ All checks passed (0Dviolations; only the intentionally-ignoredD100–D107remain).ruff format --check slack_bolt/ tests/ examples/→ clean/idempotent../scripts/lint.sh --no-install→ green../scripts/run_mypy.sh --no-install→ no new errors vsmain.Category
slack_bolt.Appand/or its core componentsslack_bolt.async_app.AsyncAppand/or its core componentsslack_bolt.adapter/docsRequirements
./scripts/install_all_and_run_tests.shafter making the changes.