Skip to content

Drop docstring parameters that are not in the signature - #20205

Merged
pllim merged 2 commits into
astropy:mainfrom
darkdi:fix/docstring-params-not-in-signature
Aug 5, 2026
Merged

Drop docstring parameters that are not in the signature#20205
pllim merged 2 commits into
astropy:mainfrom
darkdi:fix/docstring-params-not-in-signature

Conversation

@darkdi

@darkdi darkdi commented Aug 5, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

AI assistance

Per the astropy AI policy: the mismatches were surfaced by a sweep comparing
numpydoc parameter names against the actual signatures, run with Claude in
Claude Code, which also wrote the patch. I read every finding against its
signature and body before changing it, checked the neighbouring blocks that the
sweep also flagged and left the correct ones alone, and the four I could not
call unambiguous are listed above rather than edited.

Description

Eight Parameters entries across four subpackages document a name the function does not accept. Each was read against its signature and body before changing.

Where Documented Actual
astropy/wcs/wcs.py:3421 WCS.dropaxis wcs describes self; the only parameter is dropax
astropy/wcs/wcs.py:3446 WCS.swapaxes wcs describes self; the parameters are ax0, ax1
astropy/modeling/bounding_box.py:497 _BoundingDomain._evaluate valid_inputs, valid_index both are locals, produced by self.prepare_inputs(...) on the first line of the body; the real parameter inputs was undocumented
astropy/modeling/bounding_box.py:557 _BoundingDomain.evaluate valid_inputs, valid_index same, and inputs again undocumented
astropy/io/fits/diff.py:723 HeaderDiff.__init__ numdiffs not in this signature; FITSDiff.__init__ does take it and documents it correctly
astropy/modeling/_fitting_parallel.py:385 parallel_fit_dask data_units the parameter is data_unit, as is the name the @support_nddata decorator maps to and the name used throughout the body

The two in bounding_box.py have a visible cause: _evaluate_model directly above really does take valid_inputs and valid_index, and its docstring is correct. The block was copied down to two functions whose signature takes inputs instead. I replaced those two entries with inputs rather than only deleting them, so the sections now match their signatures.

wcs in the two WCS methods reads as a leftover from a free-function form, dropaxis(wcs, dropax).

Docstrings only — no signature, call site, or behaviour is touched.

Left alone deliberately

The same sweep raised four more that I did not change, because they are not defects or not mine to decide:

  • astropy/modeling/fitting.py:522 and :1341, __call__ documenting equivalencies. The @fitter_unit_support decorator does kwargs.pop("equivalencies", None), so the parameter is genuinely accepted and the docstring is right.
  • astropy/cosmology/_src/flrw/base.py:944, angular_diameter_distance heading its section z1, z2 while the signature reads z, z2. The prose underneath explains that convention on purpose, so changing the heading may lose meaning.
  • astropy/modeling/separable.py:287, _separable — the section heading is written Returns : instead of Returns with an underline, so is_separable is parsed as a parameter. That is a real rendering bug, but a different change from this one; happy to send it separately.

Changelog

Not added: this changes docstrings only. Per development_details.rst the fragment needs the PR number, so if you would like one I will add docs/changes/<subpackage>/<this PR>.other.rst on request — or the no-changelog-entry-needed label, whichever you prefer.

@darkdi
Drop docstring parameters that are not in the signature
8fac05b 
Eight Parameters entries name something the function does not take: `self`
under an old free-function name, locals produced inside the body, a tag
copied from a parent class, and one plural typo. Docstrings only.
@darkdi
darkdi requested review from a team, mcara and saimn as code owners August 5, 2026 00:28
@github-actions

github-actions Bot commented Aug 5, 2026

Copy link
Copy Markdown
Contributor

Thank you for your contribution to Astropy! 🌌 This checklist is meant to remind the package maintainers who will review this pull request of some common things to look for.

  • Do the proposed changes actually accomplish desired goals?
  • Do the proposed changes follow the Astropy coding guidelines?
  • Are tests added/updated as required? If so, do they follow the Astropy testing guidelines?
  • Are docs added/updated as required? If so, do they follow the Astropy documentation guidelines?
  • Is rebase and/or squash necessary? If so, please provide the author with appropriate instructions. Also see instructions for rebase and squash.
  • Did the CI pass? If no, are the failures related? If you need to run daily and weekly cron jobs as part of the PR, please apply the "Extra CI" label. Codestyle issues can be fixed by the bot.
  • Is a change log needed? If yes, did the change log check pass? If no, add the "no-changelog-entry-needed" label. If this is a manual backport, use the "skip-changelog-checks" label unless special changelog handling is necessary.
  • Is this a big PR that makes a "What's new?" entry worthwhile and if so, is (1) a "what's new" entry included in this PR and (2) the "whatsnew-needed" label applied?
  • At the time of adding the milestone, if the milestone set requires a backport to release branch(es), apply the appropriate "backport-X.Y.x" label(s) before merge.

@pllim pllim added this to the v8.1.0 milestone Aug 5, 2026
@pllim pllim modified the milestones: v8.1.0, v7.2.3 Aug 5, 2026
@pllim pllim added Bug backport-v7.2.x on-merge: backport to v7.2.x backport-v8.0.x on-merge: backport to v8.0.x labels Aug 5, 2026
@pllim

pllim commented Aug 5, 2026

Copy link
Copy Markdown
Member

If you mean this, might as well fix it here also. It is hidden function, so the doc is not rendered but no harm fixing. Thanks.

astropy/astropy/modeling/separable.py

Line 296 in 1d2de44

Returns :

@darkdi

darkdi commented Aug 5, 2026

Copy link
Copy Markdown
Contributor Author

Yes, that's the one. Fixed in the latest commit — the heading is now Returns
with an underline, so the section parses as a return value rather than a
parameter. Thanks for the quick look.

pllim
pllim approved these changes Aug 5, 2026
View reviewed changes

@pllim pllim left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Thanks!

@pllim

pllim commented Aug 5, 2026

Copy link
Copy Markdown
Member

Thank you for being forthcoming in your AI usage.

As for the remaining issues you are unsure how to fix, please open an issue per problem, especially if they are in different subpackages, if you so desire.

This was referenced Aug 5, 2026
Closed
Open
Closed
@darkdi

darkdi commented Aug 5, 2026

Copy link
Copy Markdown
Contributor Author

Opened three, one per problem:

The two equivalencies entries in modeling/fitting.py turned out not to be problems at all — @fitter_unit_support pops equivalencies out of **kwargs, so the docstrings are right and the signature alone is misleading. Same for format in cosmology/funcs/comparison.py: _comparison_decorator states in its Notes that every decorated function should document it. Both left alone.

@pllim
pllim merged commit 3f1abc6 into astropy:main Aug 5, 2026
37 of 38 checks passed
@pllim

pllim commented Aug 5, 2026

Copy link
Copy Markdown
Member

Thanks!

This was referenced Aug 5, 2026
Merged
Merged
pllim pushed a commit that referenced this pull request Aug 5, 2026
@darkdi @meeseeksmachine
Backport PR #20205: Drop docstring parameters that are not in the sig…
eb6cba1 
…nature
pllim added a commit that referenced this pull request Aug 5, 2026
@pllim @darkdi
Backport PR #20205: Drop docstring parameters that are not in the sig…
6d9b3a7 
…nature (#20209)

Co-authored-by: Dmitry <[email protected]>
pllim pushed a commit that referenced this pull request Aug 5, 2026
@darkdi @meeseeksmachine
Backport PR #20205: Drop docstring parameters that are not in the sig…
be1fea5 
…nature
pllim added a commit that referenced this pull request Aug 5, 2026
@pllim
Merge pull request #20210 from meeseeksmachine/auto-backport-of-pr-20…
b3f8e75 
…205-on-v8.0.x

Backport PR #20205 on branch v8.0.x (Drop docstring parameters that are not in the signature)
MaanasArora pushed a commit to MaanasArora/astropy that referenced this pull request Aug 10, 2026
@darkdi @MaanasArora
Merge pull request astropy#20205 from darkdi/fix/docstring-params-not…
95f3809 
…-in-signature

Drop docstring parameters that are not in the signature
siddartha018 pushed a commit to siddartha018/astropy that referenced this pull request Sep 27, 2026
@darkdi
Merge pull request astropy#20205 from darkdi/fix/docstring-params-not…
bd9abe9 
…-in-signature
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@pllim pllim pllim approved these changes
@mcara mcara Awaiting requested review from mcara mcara is a code owner
@saimn saimn Awaiting requested review from saimn saimn is a code owner

Assignees

No one assigned

Labels

backport-v7.2.x on-merge: backport to v7.2.x backport-v8.0.x on-merge: backport to v8.0.x Bug Docs io.fits modeling no-changelog-entry-needed wcs

Projects

None yet

Milestone

v7.2.3

Development

Successfully merging this pull request may close these issues.

2 participants

@darkdi @pllim