Skip to content

DOC: Fix parameter names in private helper docstrings - #14134

Open
karpovantonme wants to merge 3 commits into
mne-tools:mainfrom
karpovantonme:doc/param-names-match-signature
Open

DOC: Fix parameter names in private helper docstrings#14134
karpovantonme wants to merge 3 commits into
mne-tools:mainfrom
karpovantonme:doc/param-names-match-signature

Conversation

@karpovantonme

Copy link
Copy Markdown
Contributor

Ten docstrings name a parameter the function does not take. All in private helpers, so nothing here is user facing, but help() and editor tooltips are what a developer reads when working on this code.

Renames, one to one

Where Documented Signature
_lin_field_coeff, _do_lin_field_coeff rmag, cosmag rmags, cosmags
write_named_matrix matkind mat
_abstract.text2d x, y x_window, y_window
_cart_to_sph cart_pts cart
_sss_basis coils all_coils

The first pair is nice: the line right under it already reads "The sensor assignments for each rmag/cosmag/w", so the singular is the element and the parameter is the plural. write_named_matrix documented matkind, which does not exist, and left the real mat undocumented.

One wrong default

_ajd_pham documents max_iter : int, default 1000, the signature is max_iter=15. That is off by a factor of 66, and it is the kind of number someone reads before deciding whether the algorithm converged. pyRiemann, which the comment right below credits as the source of this implementation, uses n_iter_max=20, so 1000 does not come from there either. I did not touch the code, only the number in the docstring.

Ten more I did not touch

The same sweep flags ten where the parameter was not renamed but removed or split, so the fix is a judgement call rather than a rename:

  • _fft_multiply_repeated documents h_fft and n_fft, both now live inside cuda_dict
  • _prep_field_computation documents rr and fwd_data, signature is (sensors, bem, n_jobs, verbose)
  • _sph_to_cart_partials documents sph_grads, which became five separate arguments
  • calculate_lut documents lim_cmap, gone entirely
  • plus _fast_sphere_dot_r0 (rr1), _bcd (n_positions), _read_segment (projector), _n_colors (bytes vs bytes_)

Those need someone who knows whether the description should be dropped or rewritten for the new arguments. Point at any of them and I will send a follow-up.

Checks

Docstrings only, no code touched. The sweep reported 19 before and 10 after, and the ten left are exactly the list above.

AI assistance, per the policy: the mismatches were surfaced by a sweep that compares numpydoc Parameters names against the actual signature, run with Claude Opus in Claude Code, which also applied the renames and looked up the pyRiemann default. Each one was checked against the parsed signature before the edit, and I read the diff before submitting. Same setup as #14124 and #14125.

@larsoner larsoner 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.

FYI we have started gradually removing params from many of these docstrings because they tend to get out of date quickly. That said, these seem like pretty straightforward improvements so I'm okay with merging once the changelog issue is addressed

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.

Accidentally committed?

Ten docstrings name a parameter that is not in the signature, so
help() and editor tooltips show an argument that raises TypeError.

Renames, one to one:
- _lin_field_coeff and _do_lin_field_coeff: rmag/cosmag -> rmags/cosmags.
  The line just below already says 'for each rmag/cosmag/w', so the
  singular there is the element, the parameter is the plural.
- write_named_matrix: matkind -> mat. mat was undocumented.
- text2d: x/y -> x_window/y_window.
- _cart_to_sph: cart_pts -> cart.
- _sss_basis: coils -> all_coils.

And one wrong default: _ajd_pham documents max_iter=1000, the signature
has 15. pyRiemann, which the comment credits as the source, uses 20.

Docstrings only.
@karpovantonme
karpovantonme force-pushed the doc/param-names-match-signature branch from 52befad to a84cfcd Compare August 5, 2026 12:24
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