Skip to content

docs: fix documented parameter names that do not match the signature - #4156

Open
massimiliano1991 wants to merge 1 commit into
huggingface:mainfrom
massimiliano1991:docs/fix-param-name-mismatches
Open

docs: fix documented parameter names that do not match the signature#4156
massimiliano1991 wants to merge 1 commit into
huggingface:mainfrom
massimiliano1991:docs/fix-param-name-mismatches

Conversation

@massimiliano1991

Copy link
Copy Markdown

What

Three docstrings document a parameter name that does not exist in the function signature:

location documented actual
utils/operations.py recursively_apply main_type test_type
tracking.py SwanLabTracker.log data values
tracking.py MLflowTracker.log_figure **kwargs **save_kwargs

Why it's worth fixing

For the first two the mismatch is not only cosmetic. Both functions accept **kwargs, so a
keyword copied from the documentation is not rejected at the boundary — it is swallowed and
forwarded to the user's own callback:

>>> recursively_apply(my_fn, data, main_type=torch.Tensor)   # as documented
TypeError: my_fn() got an unexpected keyword argument 'main_type'

The traceback names my_fn, not recursively_apply, so nothing points back to the docstring
that suggested the argument.

recursively_apply's docstring also describes main_type as a type defaulting to
torch.Tensor, while test_type is a predicate defaulting to is_torch_tensor. The three
other references to main_type in the same docstring (including the Returns: line) are
updated to match.

For MLflowTracker.log_figure the ** form absorbs any name, so there is no error — but the
docstring also pointed at mlflow.log_image rather than mlflow.log_figure. The surrounding
Args: block had its description lines un-indented, which breaks rendering, so those lines are
re-indented to the style used by the rest of the file. SwanLabTracker.log had the same issue
and now matches the other trackers' log methods in that module.

How these were found

Mechanically: parsing each Args: block and diffing it against the ast signature, then
checking each hit by hand. Only these three came out as documented-but-absent across
src/accelerate.

Checks

  • docs only — no behaviour change, no public API touched
  • ruff format --check clean on both files; ruff check reports only pre-existing findings in
    untouched lines

Three docstrings document a parameter name that does not exist in the
function signature:

- recursively_apply: documents `main_type`, the parameter is `test_type`
- SwanLabTracker.log: documents `data`, the parameter is `values`
- MLflowTracker.log_figure: documents `**kwargs`, the parameter is `**save_kwargs`

For the first two the mismatch is not just cosmetic: both functions accept
`**kwargs`, so a keyword taken from the docs is silently swallowed and
forwarded. `recursively_apply(func, data, main_type=X)` raises
"<user function>() got an unexpected keyword argument 'main_type'" -
an error that names the caller's own function, not the one with the wrong docs.

Docs only, no behaviour change.
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.

1 participant