Document feature flags

[Lorak-mmk]

Our crates have a lot of feature flags.
scylla:

scylla-rust-driver/scylla/Cargo.toml

Lines 17 to 43 in 0142025

	[features]
	default = []
	openssl-010 = ["dep:tokio-openssl", "dep:openssl"]
	rustls-023 = ["dep:tokio-rustls", "dep:rustls"]
	unstable-cloud = [
	"scylla-cql/serde",
	"dep:serde_yaml",
	"dep:serde",
	"dep:url",
	"dep:base64",
	]
	secrecy-08 = ["scylla-cql/secrecy-08"]
	chrono-04 = ["scylla-cql/chrono-04"]
	time-03 = ["scylla-cql/time-03"]
	num-bigint-03 = ["scylla-cql/num-bigint-03"]
	num-bigint-04 = ["scylla-cql/num-bigint-04"]
	bigdecimal-04 = ["scylla-cql/bigdecimal-04"]
	full-serialization = [
	"chrono-04",
	"time-03",
	"secrecy-08",
	"num-bigint-03",
	"num-bigint-04",
	"bigdecimal-04",
	]
	metrics = ["dep:histogram"]
	unstable-testing = []

scylla-cql:

scylla-rust-driver/scylla-cql/Cargo.toml

Lines 77 to 91 in 0142025

	[features]
	secrecy-08 = ["dep:secrecy-08"]
	time-03 = ["dep:time-03"]
	chrono-04 = []
	num-bigint-03 = ["dep:num-bigint-03"]
	num-bigint-04 = ["dep:num-bigint-04"]
	bigdecimal-04 = ["dep:bigdecimal-04"]
	full-serialization = [
	"chrono-04",
	"time-03",
	"secrecy-08",
	"num-bigint-03",
	"num-bigint-04",
	"bigdecimal-04",
	]

They really lack any documentation.
docs.rs has this page: https://docs.rs/crate/scylla/latest/features , but as expected there is very little information there.
They recommend a few places to write feature flags docs in: readme, main docs page, Cargo.toml.
We should choose one and write them.

Personally I think Cargo.toml is the best place (+ linking to it from readme / main docs page).
Why? It pretty much eliminates risk of docs getting out of sync with definitions. It also allows us to keep docs close to the thing they document.

[wprzytula]

Personally I think Cargo.toml is the best place (+ linking to it from readme / main docs page).
Why? It pretty much eliminates risk of docs getting out of sync with definitions. It also allows us to keep docs close to the thing they document.

While I agree that putting feature descriptions in Cargo.toml is the best way to keep descriptions and the very features in-sync, I also think that discoverability matters. For example, take a look at tokio crate docs front page. They have a dedicated section that talks about crate features, lists them and describes them.

I believe we should at least have a section that says, "We have many features that are only available behind feature flags. For a list of them & description, see Cargo.toml".
Another possible compromise would be to maintain a list of features in both places, but have the description in Cargo.toml only. I doubt this would be a better solution, though.

[Lorak-mmk]

I believe we should at least have a section that says, "We many features that are only available behind feature flags. For a list of them & description, see Cargo.toml".

This is what I meant by "(+ linking to it from readme / main docs page).". Have a section that explains where to find feature flags docs, and provides a link to them.