doc_auto_cfg formatting is not that great

[ChrisDenton]

cargo doc has a new doc_auto_cfg feature that finally seems to figure this out based on cfg attributes so we don't have to generate the redundant doc comments any longer. rust-lang/rust#43781

Unfortunately, formatting is not that great.

originally posted by @kennykerr

[GuillaumeGomez]

I'll try to change the display because it's really not great.

[tim-weis]

I wonder whether the formatting is the issue rather than the algorithm used to discover the required features. The formatting goes awry in the example above due to the large number of (redundant) features:

• Win32
• Win32_System
• Win32_System_Diagnostics
• Win32_System_Diagnostics_Debug

That's technically correct, but not entirely helpful to a developer either. windows' Cargo.toml has the following entries in its [features] table:

[features]
Win32_System = ["Win32"]
Win32_System_Diagnostics = ["Win32_System"]
Win32_System_Diagnostics_Debug = ["Win32_System_Diagnostics"]

To use OutputDebugStringW, the only feature a client needs to enable is Win32_System_Diagnostics_Debug. The remaining features are automatically enabled recursively via the Cargo.toml. It would seem reasonable to prune the feature list by eliminating those features that are implicitly enabled. Doing this solves two issues:

• It makes the formatting a non-issue (here).
• It declutters the documentation, showing only information that clients can act upon.

I'm not aware of a way to cancel automatic enablement of dependent features, so dropping this information from the documentation should be inconsequential in practice.

---

If the formatting is being reworked nonetheless, here's what I'd like to see:

• Enclose the feature names in ASCII double quotes (") for convenient copy-pasting. The windows crate uses backticks to prevent them from being converted to smart quotes.
• Make the list comma-separated (again, for convenient copy-pasting). I understand that and (as used currently) carries semantic information that needs to be reflected elsewhere. If or is being used, it can remain as-is. We commonly don't need to copy-paste disjunct features.