user0/rust
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Remove doc_cfg related content from rustdoc book unstable features chapter

Browse source
This commit is contained in:
Guillaume Gomez 2025-04-07 17:07:21 +02:00
parent 18df897221
commit d6ba93a3fe
1 changed files with 0 additions and 82 deletions
Download patch file Download diff file Expand all files Collapse all files

82
src/doc/rustdoc/src/unstable-features.md
View file

@ -56,88 +56,6 @@ It is also not emitted for foreign items, aliases, extern crates and imports.
These features operate by extending the `#[doc]` attribute, and thus can be caught by the compiler
and enabled with a `#![feature(...)]` attribute in your crate.
### `#[doc(cfg)]`: Recording what platforms or features are required for code to be present
* Tracking issue: [#43781](https://github.com/rust-lang/rust/issues/43781)
You can use `#[doc(cfg(...))]` to tell Rustdoc exactly which platform items appear on.
This has two effects:
1. doctests will only run on the appropriate platforms, and
2. When Rustdoc renders documentation for that item, it will be accompanied by a banner explaining
that the item is only available on certain platforms.
`#[doc(cfg)]` is intended to be used alongside [`#[cfg(doc)]`][cfg-doc].
For example, `#[cfg(any(windows, doc))]` will preserve the item either on Windows or during the
documentation process. Then, adding a new attribute `#[doc(cfg(windows))]` will tell Rustdoc that
the item is supposed to be used on Windows. For example:
```rust
#![feature(doc_cfg)]
/// Token struct that can only be used on Windows.
#[cfg(any(windows, doc))]
#[doc(cfg(windows))]
pub struct WindowsToken;
/// Token struct that can only be used on Unix.
#[cfg(any(unix, doc))]
#[doc(cfg(unix))]
pub struct UnixToken;
/// Token struct that is only available with the `serde` feature
#[cfg(feature = "serde")]
#[doc(cfg(feature = "serde"))]
#[derive(serde::Deserialize)]
pub struct SerdeToken;
```
In this sample, the tokens will only appear on their respective platforms, but they will both appear
in documentation.
`#[doc(cfg(...))]` was introduced to be used by the standard library and currently requires the
`#![feature(doc_cfg)]` feature gate. For more information, see [its chapter in the Unstable
Book][unstable-doc-cfg] and [its tracking issue][issue-doc-cfg].
### `doc_auto_cfg`: Automatically generate `#[doc(cfg)]`
* Tracking issue: [#43781](https://github.com/rust-lang/rust/issues/43781)
`doc_auto_cfg` is an extension to the `#[doc(cfg)]` feature. With it, you don't need to add
`#[doc(cfg(...)]` anymore unless you want to override the default behaviour. So if we take the
previous source code:
```rust
#![feature(doc_auto_cfg)]
/// Token struct that can only be used on Windows.
#[cfg(any(windows, doc))]
pub struct WindowsToken;
/// Token struct that can only be used on Unix.
#[cfg(any(unix, doc))]
pub struct UnixToken;
/// Token struct that is only available with the `serde` feature
#[cfg(feature = "serde")]
#[derive(serde::Deserialize)]
pub struct SerdeToken;
```
It'll render almost the same, the difference being that `doc` will also be displayed. To fix this,
you can use `doc_cfg_hide`:
```rust
#![feature(doc_cfg_hide)]
#![doc(cfg_hide(doc))]
```
And `doc` won't show up anymore!
[cfg-doc]: ./advanced-features.md
[unstable-doc-cfg]: ../unstable-book/language-features/doc-cfg.html
[issue-doc-cfg]: https://github.com/rust-lang/rust/issues/43781
### Adding your trait to the "Notable traits" dialog
* Tracking issue: [#45040](https://github.com/rust-lang/rust/issues/45040)