Skip to content

fix(settings): keep doc comments on fields with serde(rename) - #320

Open
0z5a wants to merge 1 commit into
cloudflare:mainfrom
0z5a:fix-settings-rename-doc-comments
Open

0z5a wants to merge 1 commit into
cloudflare:mainfrom
0z5a:fix-settings-rename-doc-comments

Conversation

@0z5a

@0z5a 0z5a commented Nov 21, 2026

Copy link
Copy Markdown

#[settings] keys each field's doc comments by the field's Rust name. A field with #[serde(rename = "...")] is serialized under the renamed key, so its doc comments, and those of any struct nested under it, were missing from to_yaml_string, to_yaml_file and Cli's --generate output.

The key now comes from the field's serde(rename) when there is one: the string for rename = "...", or the serialize name for rename(serialize = "...", deserialize = "..."). Without a rename, the key is the field name with the r# prefix removed, as it is now (#299).

rename is parsed separately from SerdeArgs, because serde also accepts the two names in separate arguments, e.g. #[serde(rename(deserialize = "a"))] together with #[serde(rename(serialize = "b"))]. Adding rename to SerdeArgs would make darling reject that as a duplicate field, and such a struct would stop compiling.

Struct-level rename_all is not handled. As far as I can tell it can't be used on a #[settings] struct today: on current stable, #[serde(...)] below #[settings] is rejected by the legacy_derive_helpers lint, and above it serde's attribute isn't in scope yet.

Fixes #319

How I found it

I was reading how #[settings] builds the doc comment keys after #299 and saw that the key is always derived from the identifier, while serde can serialize the field under another name. I then checked it with a small struct that has renamed fields.

Where this can show up in practice

rename is the usual way to give a setting a key that isn't a valid Rust identifier, such as listen-addr. Every renamed field and everything nested under it is then undocumented in the generated config file. Deserialization is not affected.

Before

---
listen-addr: 0
upstream:
  a: 0
  b: 11
  c: 0

After

---
# A field with a serde rename.
listen-addr: 0
# A nested struct with separate serialize and deserialize names.
upstream:
  # A field, which is named the same as another field.
  a: 0
  # multi-line
  # doc comment
  b: 11
  c: 0

Testing

On macOS:

  • Added renamed_field_doc_comments to foundations/tests/settings.rs, with expected output for both YAML backends. One field uses rename = "..." and the nested one uses separate rename(deserialize = ...) and rename(serialize = ...) attributes. The test fails on main (the output above) and passes with the fix.
  • Control: a struct with rename(serialize = ...) and rename(deserialize = ...) in two attributes, and both in one attribute, compiles on main and with this change.
  • cargo test -p foundations --no-default-features --features settings --test settings: 15 passed, with and without --features serde-saphyr.
  • cargo test -p foundations-macros: all tests pass.
  • cargo fmt --all -- --check and the clippy command from AGENTS.md (on -p foundations-macros --all-targets and -p foundations --test settings) are clean.

The doc comments of a field were keyed by its Rust name, so a field with
#[serde(rename = "...")] lost them, and so did the fields of a struct
nested under it. Use the serialize name of the rename instead.
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.

settings: doc comments are dropped for fields with #[serde(rename)]

1 participant