RFC: Rework feature documentation

[zeylahellyer]

What?

Rework how we document features to make our crate documentation leaner, more concise, and open up documentation "real estate" to enable documenting more about what the crates actually are.

Why?

The crate-level documentation for the gateway crate has 74 lines of textual documentation, excluding newlines. Of this, 2 are dedicated to the header and badge links, 10 for what the crate is, 3 for pointing to the in-repository examples, and the remaining 59 are dedicated to documenting features. It's possible to continue documenting feature inline to the crate documentation while drastically reducing the line count, freeing up space for documentation on what the crate is, why you would use it, and an example of what using it looks like.

How?

Create a list of feature names paired with their description. On the surface this could make it unclear which features are grouped together or mutually exclusive, so we can make sub-lists for each category where necessary. Here's what the documentation for TLS features in the gateway crate looks like:

TLS

twilight-gateway has features to enable [tokio-tungstenite] and
[twilight-http]'s TLS features. These features are mutually exclusive.
rustls-native-roots is enabled by default.

native

The native feature enables [tokio-tungstenite]'s native-tls
feature as well as [twilight-http]'s native feature which is mostly
equivalent to using native-tls.

To enable native, do something like this in your Cargo.toml:

[dependencies]
twilight-gateway = { default-features = false, features = ["native"], version = "0.2" }

rustls-native-roots

The rustls-native-roots feature enables [tokio-tungstenite]'s rustls-tls-native-roots feature and
[twilight-http]'s rustls-native-roots feature, which use rustls as the TLS backend and rustls-native-certs
for root certificates.

This is enabled by default.

rustls-webpki-roots

The rustls-webpki-roots feature enables [tokio-tungstenite]'s rustls-tls-webpki-roots feature and
[twilight-http]'s rustls-webpki-roots feature, which use rustls as the TLS backend and webpki-roots
for root certificates.

This should be preferred over rustls-native-roots in Docker containers based on scratch.

This is a lot of repeated information. Information that, as it is, is repeated, quite a lot. To reduce the amount of repeated information, we can remove the repetition by simplifying all of this documented TLS information into a list:

• native: platform's native TLS implementation via native-tls equivalents
• rustls-native-roots: rustls using native root certificates
• rustls-webpki-roots: rustls using webpki-roots for root certificates,
  useful for scratch containers

If we make a list for everything then it looks pretty good:

• simd-json: use simd-json instead of serde_json to deserialize events
• TLS (mutually exclusive)
  • native: platform's native TLS implementation via native-tls equivalents
  • rustls-native-roots (default): rustls using native root certificates
  • rustls-webpki-roots: rustls using webpki-roots for root certificates, useful for scratch containers
• Zlib (mutually exclusive)
  • zlib-stock (default): flate2's stock zlib implementation
  • zlib-simd: use zlib-ng for zlib, may have better performance

And that's it! This just reduced 59 lines of documentation into 8.

After the library's website is revamped we can also point to our website for additional information on the benefits and drawbacks of each of these options are (why choose rustls-native-roots over rustls-webpki-roots?), but for now this would reduce the size of the documentation while not taking important information away and pointing users to resources that can educate them on what simd-json or rustls are.

[laralove143]

i think it'd also make sense to add "(required)" or "*" to parents in the list, to indicate one of the features is required, and for optional parents, a "none" item would be useful to say when you wouldn't enable anything, like http's TLS feature not being enabled for proxy usages