Document Cargo feature flags

[emilk]

document-features is a crate for easily documenting the feature flags in the Cargo.toml file.

[madsmtm]

I'd rather just document them manually, as exemplified in the regex crate.

Also, looking at the feature flags we do have, I think serde, rwh_04/rwh_05/rwh_06 and maybe x11/wayland should be documented in the crate root, while the backend-specific ones should be documented in the relevant platform module.

[emilk]

The downside of documenting them manually is that you need to keep the documentation and Cargo.toml in sync, with the ever-looming risk of them diverging. So I recommend the document-feature crate as it makes it very simple to document the features and keep them documented. But 🤷

[daxpedda]

I would also prefer to have the process automated, but I think document-feature comes with it's own set of problems:

• Guarding it behind a crate feature is probably a bad idea for obvious reasons.
• Guarding it behind cfg(docsrs) is also a bad idea because we use nightly features with that.
• So we need something new, cfg(document-feature), which also means that if users are not aware of that when generating their own documentation with cargo doc they will miss out on it.
• Not guarding it isn't an option because it pulls in proc-macro2, which many of our backends were able to successfully mitigate so far.

None of these are real showstoppers though, just some downsides. I would have preferred to have a tool that checks it in CI instead of a Cargo dependency parsing things in a proc-macro during build. Alternatively a fix in Cargo would do it as well: rust-lang/cargo#2025, rust-lang/cargo#8811.

---

I don't have a strong opinion either way, but if I had to vote on something it would probably be just doing it by hand.

[dhardy]

My personal take is that Cargo.toml is the right place to document features because it's the only place you can guarantee all features will be listed.

I'm glad we have dep: syntax now so that optional dependencies can be properly documented as features.

[kchibisov]

Could we extract features manually from the Cargo.toml when building docs, generate the .md based on that and put inside the target, optionally including/linking to it?