Skip to content

Commit

Permalink
Fix feature annotation in documentation
Browse files Browse the repository at this point in the history
Lots of things in the library are only compiled when certain features
are enabled. However, it is not always clear to the user that in order
to use an item, it will need features x, y, and z, because by default,
this information is not shown.

Fortunately, a feature in `rustdoc` is being developed to provide such
information in the documentation, `doc_cfg`, which is usable right now
in Nightly Rust. To use it, you simply had to activate the feature
somewhere (preferably the crate root) using `#![feature(doc_cfg)]` and
then add `#[doc(cfg(feature = "x"))]` on an item to display that said
item requires the `x` feature. What is awesome about this is that it can
be automatically derived for all `#[cfg(...)]` instances for you.

Unfortunately, it was found out that the auto mode isn't appropriate in
all cases and may sometimes pick the wrong `#[cfg(...)]`. For this
reason, in the "Split doc_cfg and doc_auto_cfg features" pull
request[0], the auto mode has been split into a separate feature. This
commit changes the feature activation line in `lib.rs` to use
`doc_auto_cfg` instead of `doc_cfg`.

[0]: rust-lang/rust#90502
  • Loading branch information
arqunis committed Feb 25, 2022
1 parent 91ee596 commit 8798356
Showing 1 changed file with 1 addition and 1 deletion.
2 changes: 1 addition & 1 deletion src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@
//! [examples]: https://github.com/serenity-rs/serenity/tree/current/examples
//! [gateway docs]: crate::gateway
#![doc(html_root_url = "https://docs.rs/serenity/*")]
#![cfg_attr(docsrs, feature(doc_cfg))]
#![cfg_attr(docsrs, feature(doc_auto_cfg))]
#![deny(rust_2018_idioms)]
#![deny(broken_intra_doc_links)]
#![deny(
Expand Down

0 comments on commit 8798356

Please sign in to comment.