Skip to content

docs: fix two docstrings that reference names the code does not have - #14733

Open
iridescentWen wants to merge 2 commits into
huggingface:mainfrom
iridescentWen:docs/stale-refs-diffusers
Open

docs: fix two docstrings that reference names the code does not have#14733
iridescentWen wants to merge 2 commits into
huggingface:mainfrom
iridescentWen:docs/stale-refs-diffusers

Conversation

@iridescentWen

Copy link
Copy Markdown
Contributor

Fixes #14732

What's wrong

Two docstrings name something the function does not have, so following the docs leads nowhere.

File Line Docstring said Reality
models/transformers/transformer_ltx2.py 1449 `peturbation_mask` perturbation_mask — spelled correctly at :253, :273, :314, :316, :623; the class docstring at :233 also reads "perturbation masking". Only this reference drops the r.
pipelines/deprecated/.../pipeline_stable_diffusion_diffedit.py 885, 888 `source_image` imagegenerate_mask has no source_image parameter.

For the second one, the parameter list is:

['image', 'target_prompt', 'target_negative_prompt', 'target_prompt_embeds',
 'target_negative_prompt_embeds', 'source_prompt', 'source_negative_prompt',
 'source_prompt_embeds', 'source_negative_prompt_embeds', ...]

The source_prompt* names those two lines mention alongside it are real, which is what makes the
wrong one misleading rather than obviously broken.

Docstrings only, no behavior change.

Validation

$ uvx ruff check <the 2 changed files>
All checks passed!

$ uvx ruff format --check <the 2 changed files>
2 files already formatted

git diff --stat: 2 files, +3/-3.

Self-review (per CONTRIBUTING)

Ran the .ai/skills/self-review rubric against .ai/review-rules.md:

  • Blocking issues: none. Docstring text only.
  • # Copied from: checked per changed hunk — forward (transformer_ltx2.py:1366) and
    generate_mask (diffedit:845) carry no # Copied from header, so editing them directly is
    correct rather than fixing an upstream source and running make fix-copies.
    utils/check_copies.py is outside my sparse checkout, so this is the manual equivalent; CI's
    consistency check will confirm.
  • Ephemeral context: none added.
  • Documentation impact: this is the documentation fix; no docs/ page repeats either name.
  • Dead code analysis: N/A.

Deliberately excluded

The same AST pass surfaced two larger clusters that I am not touching, so they read as reviewed
rather than missed:

  • alpha_bar, 27 sites across the scheduler files. The docstrings say "Contains a function
    alpha_bar" while the inner function is alpha_bar_fn. That is a conceptual description of what
    the helper does rather than a broken pointer, the sites are linked by # Copied from, and 27 edits
    across that many files is a different kind of change. Happy to send it if you consider it worth
    fixing.
  • enhance_t2v / enhance_i2v / generate_enhanced_prompt, 15 sites. These name helpers that do
    not exist anywhere in src/diffusers, so they may be intentional references to external example
    code. I did not want to guess.

The scan needed two rounds of narrowing before it was usable, which is worth stating so the two hits
above are not mistaken for a broad sweep: a module-local symbol table produced far too many hits
because docstrings legitimately reference sibling modules, and lines shaped - `key`: description
enumerate an upstream API's keys rather than the function's own parameters. Both are now excluded.


🤖 Written with Claude Code. Both sites were read in context and the
corrected names were taken from the signature and from the surrounding correct spellings.

- transformer_ltx2.py:1449 says `peturbation_mask`; the parameter is
  `perturbation_mask`, spelled correctly at :253, :273, :314, :316, :623.
- pipeline_stable_diffusion_diffedit.py:885,:888 point at `source_image`,
  but generate_mask's image argument is `image`.

Fixes huggingface#14732

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@stevhliu

stevhliu commented Sep 8, 2026

Copy link
Copy Markdown
Member

thanks, if you have any more fixes similar to this, feel free to add it to this PR

Each documents a name the signature no longer has:

- optimization.py:161      num_periods        -> num_cycles
- autoencoder_kl_ltx2.py:43 dim               -> channel_dim
- z_image/before_denoise.py:100 vae_scale_factor -> vae_scale_factor_spatial

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@iridescentWen

Copy link
Copy Markdown
Contributor Author

Thanks — added three more in 68c7626, all the same class (a docstring naming something the
signature does not have), now 5 fixes across 5 files, +6/-6.

The three new ones are parameters that were renamed without the docstring following:

File Line Docstring said Signature
optimization.py 161 num_periods num_cycles
models/autoencoders/autoencoder_kl_ltx2.py 43 dim channel_dim
modular_pipelines/z_image/before_denoise.py 100 vae_scale_factor vae_scale_factor_spatial

Each verified against the real parameter list via AST, and none of the three sits under a
# Copied from header, so editing them directly is correct. ruff check / ruff format --check
clean on all five files.

What I looked at and chose not to include

Since you asked for more of the same, it is worth saying which candidates I rejected and why — three
clusters looked like this class but are not:

  • alpha_bar, 27 sites across the schedulers. The docstrings say "Contains a function
    alpha_bar" while the inner helper is alpha_bar_fn. On reading them, these are describing the
    concept the schedule computes, not pointing at a symbol — and 25 of the 27 carry
    # Copied from diffusers.schedulers.scheduling_ddpm.betas_for_alpha_bar, so the only correct way
    to touch them would be editing scheduling_ddpm.py and running make fix-copies. I left them
    alone; happy to do that separately if you read them as broken pointers rather than prose.
  • enhance_t2v / enhance_i2v / generate_enhanced_prompt, 15 sites. These are deliberate
    references to the upstream ltx-core / ltx-pipelines API — the surrounding lines say so
    explicitly. Correct as written.
  • tie_last_hidden_states and s_e. The first explains an upstream Qwen3VLTextModel config
    flag; the second is the symbol from equation 12 of the LEDITS++ paper. Both correct.

There is one more genuine cluster I have not put here because it is a different problem class and
would touch 19 files: 27 docstrings write a boolean default as a quoted string, e.g.
force_zeros_for_empty_prompt (`bool`, *optional*, defaults to `"True"`) in
pipeline_controlnet_sd_xl.py:222 where the signature is bool = True. Say the word and I will send
it as its own PR, per pipeline family or in one go.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Two docstrings reference names the code does not have (peturbation_mask, source_image)

2 participants