Skip to content

Add documented struct field spacing option#6926

Closed
joshka wants to merge 1 commit into
rust-lang:mainfrom
joshka:joshka/documented-struct-field-blank-lines
Closed

Add documented struct field spacing option#6926
joshka wants to merge 1 commit into
rust-lang:mainfrom
joshka:joshka/documented-struct-field-blank-lines

Conversation

@joshka
Copy link
Copy Markdown
Contributor

@joshka joshka commented May 24, 2026

Fixes #6925.

Summary

Add unstable rustfmt options for inserting blank lines around documented struct field sections:

  • documented_struct_field_blank_lines = "Preserve" | "Always" | "Threshold"
  • documented_struct_field_blank_lines_threshold = <usize>

This follows existing rustfmt config patterns better than overloading a single numeric option with a sentinel value.

Testing

  • cargo test --lib test_dump_default_config -- --nocapture
  • cargo test --lib test_dump_style_edition_2024_config -- --nocapture
  • cargo test --lib verify_config_test_names -- --nocapture
  • cargo test --lib configuration_snippet_tests -- --nocapture
  • cargo test --lib system_tests -- --nocapture

Implementation notes

  • The threshold is evaluated against the total number of fields in the struct, not the length of a contiguous documented run.
  • Once a struct qualifies, spacing is applied per contiguous documented section within that struct.
  • The implementation reuses ListItem::new_lines in the vertical field formatter instead of introducing a second spacing path.

Open points / context

  • While implementing this, the original numeric-only shape turned out to be ambiguous around 0 and 1, especially if 0 was treated as either Preserve or Always. The enum mode avoids that ambiguity.
  • The current tests cover the mode differences and threshold boundaries. They do not add dedicated interaction coverage for cases like #[rustfmt::skip] or intervening non-doc comments inside documented sections; those continue to follow the existing contiguous-section logic in vertical.rs.

AI disclosure

This PR was developed with assistance from Codex using GPT-5.5.

Add unstable rustfmt options for inserting blank lines around
contiguous documented struct field sections.

Use a Preserve/Always/Threshold mode instead of overloading a
numeric sentinel, and evaluate Threshold against the total field
count of the struct. This keeps the configuration aligned with
existing rustfmt option patterns and avoids ambiguous 0/1
threshold semantics.

Document the behavior and add focused formatter fixtures for
Preserve, Always, and threshold boundary cases.
@rustbot rustbot added the S-waiting-on-author Status: awaiting some action (such as code changes or more information) from the author. label May 24, 2026
@ytmimi
Copy link
Copy Markdown
Contributor

ytmimi commented May 26, 2026

Closing since we're not moving forward with the feature request at this time.

@ytmimi ytmimi closed this May 26, 2026
@rustbot rustbot removed the S-waiting-on-author Status: awaiting some action (such as code changes or more information) from the author. label May 26, 2026
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.

Configurable blank lines between documented struct fields

3 participants