Documentation on hierarchical env is ambiguous and could better illustrate conventions/edge cases

Hi, just wanted to offer some feedback on the documentation as a first-time user.

I'm looking at this here: https://github.com/rust-cli/config-rs/blob/main/examples/hierarchical-env/settings.rs

And I think the example could be improved to make it more obvious how it works.

This is probably the best documentation on the feature (as docs.rs didn't really clarify anything for me).

It seems like there's some ambiguity when parsing an env name.

Let's say you have a prefix of MY_APP and a separator of _. If you have some nested config value like security.app_key, then you'd expect an env var like MY_APP_SECURITY_APP_KEY.

The documentation/example doesn't really illustrate how this parsing is happening. That env name could be parsed as:

• security.app.key
• security_app.key
• security_app_key
• security.app_key

and it's not clear what rules are used to disambiguate. I'm guessing without a struct to deserialize to that all of those keys will match the env.

If I were to parse as a hashmap then I'm guessing it will just take every single underscore that isn't in the prefix as a path separator (security.app.key).

If it were deserialized to a structure with a known format then it will probably look at the fields in every layer of the hierarchy and only select matches that fit that schema.

I could imagine an extreme case like:

struct SecurityApp {
    key: String,
}
struct Security {
    app_key: String,
}
struct AppConfig {
    security: Security,
    security_app: SecurityApp,
}

Where it would either return an error (because it can't decide between security.app_key and security_app.key), or maybe it would store that value in both fields, or maybe it would store it in the first one that matches.

Other systems I've seen in the past disambiguate by defaulting to a path separator of __ (two underscores).

What I'll end up doing is experimenting through trial and error to figure out what the expectations/edge cases are, but I think it would be valuable if the documentation/examples could just make this clearer from the start. If the difference between a carefully designed schema and an ambiguous one have performance/functional implications it would be good to have clarity around that so that appropriate caution can be taken.

Start with examples/hierarchical-env/settings.rs and inspect how the hierarchical environment example describes parsing. Verify the behavior for prefixes, separators, nested keys, and ambiguous names, then update the example or documentation so the conventions and edge cases are explicit; done means a first-time user can determine how an environment name maps to configuration fields without trial and error.