Repository navigation
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #1306 +/- ##
=======================================
Coverage 91.43% 91.43%
=======================================
Files 53 53
Lines 8395 8395
=======================================
Hits 7676 7676
Misses 719 719
🚀 New features to boost your workflow:
|
jan-glx
marked this pull request as ready for review
November 9, 2026 20:30
ajkswamy
reviewed
Nov 10, 2026
ajkswamy
left a comment
ajkswamy
left a comment
Collaborator
There was a problem hiding this comment.
Since this PR introduces a significant change to the precommit config, it would be good to get at least in principle approval from all other active developers before merging this
| rev: 0.12.0 | ||
| hooks: | ||
| - id: pydoclint | ||
| files: ^src/ |
Collaborator
There was a problem hiding this comment.
please document here that args of this hook live in pyproject.toml, which will help readability and maintenability.
Collaborator
Author
There was a problem hiding this comment.
Added a comment on the hook pointing to [tool.pydoclint] in pyproject.toml.
jan-glx
force-pushed
the
jangleixner/sit-422-docstring-signature-check
branch
from
November 11, 2026 09:59
f29ebdc to
9dc47ef
Compare
jan-glx
marked this pull request as draft
November 11, 2026 10:20
…-422) Adds pydoclint as a pre-commit hook on src/, configured in [tool.pydoclint] in pyproject.toml (noted on the hook, as asked in review). Builds on the docstring fixes in jangleixner/sit-422-docstring-fixes.
jan-glx
force-pushed
the
jangleixner/sit-422-docstring-signature-check
branch
from
November 11, 2026 10:45
9dc47ef to
9771c2b
Compare
ajkswamy
pushed a commit
that referenced
this pull request
Nov 11, 2026
…422) (#1311) Docstring-only fixes split out of #1306 (SIT-422), so they can go in independently of the decision on the pydoclint hook. #1306 now contains only the hook and its config, and needs this PR merged first for its check to pass. Found by running pydoclint over `src/`: - `get_extent`: most parameters were filed under *Returns*, and the return value was described wrongly - `_bounding_box_mask_points`: a leftover `PLACEHOLDER` block, and the shared min/max coordinate docs pasted in twice - shared `min_coordinate`/`max_coordinate` docs: the first line rendered 4 spaces deeper than the rest (also on `main` in `BoundingBoxRequest` and `bounding_box_query`), and `max_coordinate` now mentions the `(n_axes,)` single-box shape like `min_coordinate` does - *Returns*/*Notes* sections that didn't parse (indented body, `-------` underline) - parameter entries written as `name: type`, which numpydoc parses as a parameter called `name: type`; the types already live in the signatures, so only the names are kept - undocumented parameters: `c_coords` (`blobs`), `suppress_z_warning`, `sdata`, `zarr_path`, `intermediate_coordinate_systems`, … - stale parameter docs (e.g. `bounding_box_query`'s dispatch-only `**kwargs`), clarified `iterate_pyramid_levels` yields - added missing Returns/Yields sections The `# noqa` comments for the intentional mismatches (singledispatch generics) are part of #1306, since they only matter with the hook. No code changes.
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
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.
Closes #1303 (SIT-422).
Depends on #1311, which fixes the docstrings this check flags (split out so they can go in independently). This PR contains only the hook, its config and the
# noqacomments below, so its pydoclint check fails until #1311 is merged.Adds pydoclint as a pre-commit hook on
src/, so CI catches docstrings that document parameters a function doesn't have, or miss ones it does (the #1273 / #1254 kind of drift).Config (
[tool.pydoclint]inpyproject.toml), kept narrow on purpose:__init__parameters (allow-init-docstring)kwargsmay be documented without stars, as the codebase already doesWhy pydoclint over numpydoc's
PR01/PR02validation: numpydoc also flags every docstring that has no Parameters section (~100 hits here, mostly private helpers). pydoclint only checks docstrings that do document parameters, so its findings are actual drift.Intentional mismatches:
ShapesModel.parse/PointsModel.parsedocument the parameters of their singledispatch overloads, andbounding_box_query's**kwargsexists only for singledispatch (no overload accepts extra arguments), so it is not documented (#1311 removes its stale entry). These get a# noqa: DOC10x;lint.external = ["DOC1"]stops ruff's RUF100 from flagging those noqa comments as unused.As suggested in review, the hook in
.pre-commit-config.yamlnotes that its options live in[tool.pydoclint]inpyproject.toml.