Repository navigation
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
#[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 fromto_yaml_string,to_yaml_fileandCli's--generateoutput.The key now comes from the field's
serde(rename)when there is one: the string forrename = "...", or theserializename forrename(serialize = "...", deserialize = "..."). Without a rename, the key is the field name with ther#prefix removed, as it is now (#299).renameis parsed separately fromSerdeArgs, because serde also accepts the two names in separate arguments, e.g.#[serde(rename(deserialize = "a"))]together with#[serde(rename(serialize = "b"))]. AddingrenametoSerdeArgswould make darling reject that as a duplicate field, and such a struct would stop compiling.Struct-level
rename_allis 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 thelegacy_derive_helperslint, 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
renameis the usual way to give a setting a key that isn't a valid Rust identifier, such aslisten-addr. Every renamed field and everything nested under it is then undocumented in the generated config file. Deserialization is not affected.Before
After
Testing
On macOS:
renamed_field_doc_commentstofoundations/tests/settings.rs, with expected output for both YAML backends. One field usesrename = "..."and the nested one uses separaterename(deserialize = ...)andrename(serialize = ...)attributes. The test fails onmain(the output above) and passes with the fix.rename(serialize = ...)andrename(deserialize = ...)in two attributes, and both in one attribute, compiles onmainand 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 -- --checkand the clippy command fromAGENTS.md(on-p foundations-macros --all-targetsand-p foundations --test settings) are clean.