Indicate when an item or impl depends on a feature

[golddranks]

Crates that have features often cause confusion. For example, the Diesel documentation shows that there exists an impl for specific trait+type combination: (in this case DB=Pg, short for PostgreSQL)
(from Diesel documentation)

impl<DB> FromSqlRow<Timestamptz, DB> for DateTime<UTC> where
    DB: Backend + HasSqlType<Timestamptz>,
    DateTime<UTC>: FromSql<Timestamptz, DB>

and again:

impl FromSql<Timestamptz, Pg> for DateTime<UTC>
impl Backend for Pg
impl HasSqlType<Timestamptz> for Pg

Yet it fails on compilation:

error[E0277]: the trait bound chrono::datetime::DateTime<chrono::offset::utc::UTC>: diesel::types::FromSqlRow<diesel::types::Timestamptz, _> is not satisfied

The problem here is that FromSql<Timestamptz, Pg> for DateTime<UTC> and thus also FromSqlRow<Timestamptz, DB> for DateTime<UTC> are implemented only when the feature "chrono" is enabled. But the docs of FromSql and FromSqlRow don't indicate this at all.

This problem is mentioned elsewhere too: #18701 (however, that issue is about the manually written doc comments on impls). Features seem to stump and baffle users.

I think that Rustdoc should clearly indicate, when an impl, or a type, trait or module, for that matter, is available only when a certain feature is enabled. That would at make the features discoverable, which they currently often aren't.

[Nemo157]

I've been working on this a bit and have a mostly working (horrible) implementation (sneak peek).

One thing I've found is that exactly where in the documentation something appears doesn't always line up nicely with where in the source tree it's defined (e.g. inherent impls can be defined in private modules for a type defined in a different public module, if that private module is affected by a feature then the only way to surface that in the docs is on the inherent impl block on the page for the struct/enum).

So, before pushing any kind of WIP implementation I'm going to try and create a simple crate showing an example of every way in which a feature could affect the documentation. Once I've got that I'll publish the docs my current implementation generates for that and try and do some design work directly on them (15 minute cycle with rebuilding rustdoc is a little slow to iterate on ☹️), then cleanup the implementation and create a PR for it.

I'll aim to get (at least the start of) the example crate up in a day or two. If there's anyone that can think of subtle ways features might influence the docs it'd be great if they could see that there's examples covering them in the crate. Or if there are any designers that may have input on how to display the features it'd be great to have some input once I have the initial sample up (I'm definitely not a designer, so having some input on this would be very useful).

[Nemo157]

Pushed an example crate: https://github.com/Nemo157/rustdoc-features-example you can see how my initial implementation documents the features at https://nemo157.com/rustdoc-features-example/impl1/rustdoc_features_example/index.html.

[Nemo157]

Pushed an almost complete implementation: https://github.com/Nemo157/rust/tree/rustdoc-features-2. Also pushed a render of the diesel docs using this implementation (e.g. the FromSql trait). Now just one small todo in the algorithmic code and need to figure out how to render it nicely before opening a PR.

[Mark-Simulacrum]

Closing in favor of #1998.