Skip to content

docs: fix docstrings whose parameters don't match the signature (SIT-422) - #1311

Merged
ajkswamy merged 2 commits into
scverse:mainfrom
jan-glx:jangleixner/sit-422-docstring-fixes
Nov 11, 2026
Merged

ajkswamy merged 2 commits into
scverse:mainfrom
jan-glx:jangleixner/sit-422-docstring-fixes

Conversation

@jan-glx

@jan-glx jan-glx commented Nov 11, 2026 •

Copy link
Copy Markdown
Collaborator

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.

…422)

Docstring-only corrections found by pydoclint (hook proposed separately in scverse#1306):
get_extent parameters filed under Returns, a PLACEHOLDER block and duplicated
min/max docs in _bounding_box_mask_points, Returns/Notes sections that didn't
parse, undocumented parameters, and missing Returns/Yields sections.
@jan-glx
jan-glx requested a review from ajkswamy November 11, 2026 08:26
@codecov

codecov Bot commented Nov 11, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 91.43%. Comparing base (bf43e7c) to head (f4408a5).

Additional details and impacted files
@@           Coverage Diff           @@
##             main    #1311   +/-   ##
=======================================
  Coverage   91.43%   91.43%           
=======================================
  Files          53       53           
  Lines        8395     8395           
=======================================
  Hits         7676     7676           
  Misses        719      719           
Files with missing lines Coverage Δ
src/spatialdata/_core/centroids.py 100.00% <ø> (ø)
src/spatialdata/_core/data_extent.py 97.97% <ø> (ø)
src/spatialdata/_core/operations/aggregate.py 89.21% <ø> (ø)
src/spatialdata/_core/operations/rasterize.py 91.43% <ø> (ø)
src/spatialdata/_core/query/relational_query.py 93.34% <ø> (ø)
src/spatialdata/_core/query/spatial_query.py 95.01% <ø> (ø)
src/spatialdata/_core/spatialdata.py 93.46% <ø> (ø)
src/spatialdata/_core/validation.py 100.00% <ø> (ø)
src/spatialdata/_io/_utils.py 87.13% <ø> (ø)
src/spatialdata/_io/io_raster.py 87.65% <ø> (ø)
... and 12 more
🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@jan-glx
jan-glx marked this pull request as draft November 11, 2026 10:19
@jan-glx
jan-glx marked this pull request as ready for review November 11, 2026 10:27
…gle-box shape for max_coordinate

The shared strings carried their own first-line indent, so wherever the
placeholder sits at the description column the first line rendered 4 spaces
too deep. Also document the (n_axes,) single-box form for max_coordinate,
as for min_coordinate.

@ajkswamy ajkswamy left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@ajkswamy
ajkswamy merged commit 602aec0 into scverse:main Nov 11, 2026
18 checks passed
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.

2 participants