Skip to content

lint: allow self-documenting builder arguments - #27507

Merged
anp-oai merged 2 commits into
mainfrom
codex/allow-self-documenting-builder-arguments
Jun 11, 2026
Merged

lint: allow self-documenting builder arguments#27507
anp-oai merged 2 commits into
mainfrom
codex/allow-self-documenting-builder-arguments

Conversation

@anp-oai

@anp-oai anp-oai commented Jun 11, 2026

Copy link
Copy Markdown
Contributor

Builder-style setters often repeat the setting name in both the method and its sole argument. Calls such as .enabled(false) are already self-documenting, so requiring /*enabled*/ adds noise without clarifying the call.

What changed

  • Exempt a method's sole non-self argument when its resolved parameter name matches the method name.
  • Continue validating any explicit argument comment against the resolved parameter name.
  • Continue requiring comments when method and parameter names differ or when a method has multiple non-self arguments.
  • Document the exception in AGENTS.md and the lint's own behavior documentation.

Examples

Before this change we'd need redundant comments like this:

builder.enabled(/*false*/ false);
builder.retry_count(/*retry_count*/ 3);
builder.base_url(/*base_url*/ None);

Now can be written like this:

builder.enabled(false);
builder.retry_count(3);
builder.base_url(None);

Still disallowed:

client.set_flag(true); // Method name does not match parameter `enabled`.
options.enabled(false, /*retry_count*/ 3); // More than one non-self argument.
options.enabled(/*value*/ false); // Explicit comment does not match `enabled`.

Validation

Added UI coverage for boolean, numeric, and None builder arguments, multi-argument methods, and explicit comment mismatches. Ran rustup run nightly-2025-09-18 cargo test in tools/argument-comment-lint.

@anp-oai
anp-oai marked this pull request as ready for review June 11, 2026 01:45
@anp-oai
anp-oai merged commit 52db447 into main Jun 11, 2026
45 of 47 checks passed
@anp-oai
anp-oai deleted the codex/allow-self-documenting-builder-arguments branch June 11, 2026 17:24
@github-actions github-actions Bot locked and limited conversation to collaborators Jun 11, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants