diff --git a/compiler/rustc_ast_passes/src/feature_gate.rs b/compiler/rustc_ast_passes/src/feature_gate.rs index 181783441f3f..948c4580d8f8 100644 --- a/compiler/rustc_ast_passes/src/feature_gate.rs +++ b/compiler/rustc_ast_passes/src/feature_gate.rs @@ -257,7 +257,6 @@ impl<'a> Visitor<'a> for PostExpansionVisitor<'a> { gate_doc!( include => external_doc - cfg => doc_cfg masked => doc_masked spotlight => doc_spotlight keyword => doc_keyword diff --git a/compiler/rustc_feature/src/accepted.rs b/compiler/rustc_feature/src/accepted.rs index 4401ec0a04ea..46307d95d499 100644 --- a/compiler/rustc_feature/src/accepted.rs +++ b/compiler/rustc_feature/src/accepted.rs @@ -274,6 +274,10 @@ declare_features! ( /// For example, you can write `Foo(a, ref b)` where `a` is by-move and `b` is by-ref. (accepted, move_ref_pattern, "1.48.0", Some(68354), None), + /// Allows `#[doc(cfg(...))]`. It adds information about under which condition an item is + /// available. + (active, doc_cfg, "1.50.0", Some(43781), None), + // ------------------------------------------------------------------------- // feature-group-end: accepted features // ------------------------------------------------------------------------- diff --git a/compiler/rustc_feature/src/active.rs b/compiler/rustc_feature/src/active.rs index a03550792479..8c38ba39d1cd 100644 --- a/compiler/rustc_feature/src/active.rs +++ b/compiler/rustc_feature/src/active.rs @@ -367,9 +367,6 @@ declare_features! ( /// Allows defining generators. (active, generators, "1.21.0", Some(43122), None), - /// Allows `#[doc(cfg(...))]`. - (active, doc_cfg, "1.21.0", Some(43781), None), - /// Allows `#[doc(masked)]`. (active, doc_masked, "1.21.0", Some(44027), None), diff --git a/library/core/src/lib.rs b/library/core/src/lib.rs index d67f9c15a191..df8db2e01966 100644 --- a/library/core/src/lib.rs +++ b/library/core/src/lib.rs @@ -104,7 +104,7 @@ #![feature(const_unreachable_unchecked)] #![feature(custom_inner_attributes)] #![feature(decl_macro)] -#![feature(doc_cfg)] +#![cfg_attr(bootstrap, doc_cfg)] #![feature(doc_spotlight)] #![feature(duration_consts_2)] #![feature(duration_saturating_ops)] diff --git a/library/std/src/lib.rs b/library/std/src/lib.rs index db523f05e01a..348a4d1015c1 100644 --- a/library/std/src/lib.rs +++ b/library/std/src/lib.rs @@ -251,7 +251,7 @@ #![feature(core_intrinsics)] #![feature(custom_test_frameworks)] #![feature(decl_macro)] -#![feature(doc_cfg)] +#![cfg_attr(bootstrap, doc_cfg)] #![feature(doc_keyword)] #![feature(doc_masked)] #![feature(doc_spotlight)] diff --git a/src/doc/rustdoc/src/advanced-features.md b/src/doc/rustdoc/src/advanced-features.md index 5128ff13b7a7..aad521b12ce5 100644 --- a/src/doc/rustdoc/src/advanced-features.md +++ b/src/doc/rustdoc/src/advanced-features.md @@ -2,6 +2,41 @@ The features listed on this page fall outside the rest of the main categories. +### `#[doc(cfg)]`: Recording what platforms or features are required for code to be present + +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)]` (described a bit below on this same +page). 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 +/// 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. + ## `#[cfg(doc)]`: Documenting platform-specific or feature-specific information For conditional compilation, Rustdoc treats your crate the same way the compiler does. Only things diff --git a/src/doc/rustdoc/src/the-doc-attribute.md b/src/doc/rustdoc/src/the-doc-attribute.md index ef143c8727ee..ff13afbcdfc0 100644 --- a/src/doc/rustdoc/src/the-doc-attribute.md +++ b/src/doc/rustdoc/src/the-doc-attribute.md @@ -214,3 +214,10 @@ the `strip-hidden` pass is removed. Since primitive types are defined in the compiler, there's no place to attach documentation attributes. This attribute is used by the standard library to provide a way to generate documentation for primitive types. + +## `#[doc(cfg)]` + +You can use `#[doc(cfg(...))]` to tell Rustdoc exactly which platform items appear on. For more +information, take a look at the [advanced-features][advanced-features] chapter. + +[advanced-features]: ./advanced-features.md diff --git a/src/doc/rustdoc/src/unstable-features.md b/src/doc/rustdoc/src/unstable-features.md index b43070510413..b5bca35c5c9f 100644 --- a/src/doc/rustdoc/src/unstable-features.md +++ b/src/doc/rustdoc/src/unstable-features.md @@ -43,51 +43,6 @@ plain text. 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 - -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]. - -[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 "Important Traits" dialog Rustdoc keeps a list of a few traits that are believed to be "fundamental" to a given type when diff --git a/src/doc/unstable-book/src/language-features/doc-cfg.md b/src/doc/unstable-book/src/language-features/doc-cfg.md deleted file mode 100644 index e75f1aea9922..000000000000 --- a/src/doc/unstable-book/src/language-features/doc-cfg.md +++ /dev/null @@ -1,46 +0,0 @@ -# `doc_cfg` - -The tracking issue for this feature is: [#43781] - ------- - -The `doc_cfg` feature allows an API be documented as only available in some specific platforms. -This attribute has two effects: - -1. In the annotated item's documentation, there will be a message saying "This is supported on - (platform) only". - -2. The item's doc-tests will only run on the specific platform. - -In addition to allowing the use of the `#[doc(cfg)]` attribute, this feature enables the use of a -special conditional compilation flag, `#[cfg(doc)]`, set whenever building documentation on your -crate. - -This feature was introduced as part of PR [#43348] to allow the platform-specific parts of the -standard library be documented. - -```rust -#![feature(doc_cfg)] - -#[cfg(any(windows, doc))] -#[doc(cfg(windows))] -/// The application's icon in the notification area (a.k.a. system tray). -/// -/// # Examples -/// -/// ```no_run -/// extern crate my_awesome_ui_library; -/// use my_awesome_ui_library::current_app; -/// use my_awesome_ui_library::windows::notification; -/// -/// let icon = current_app().get::(); -/// icon.show(); -/// icon.show_message("Hello"); -/// ``` -pub struct Icon { - // ... -} -``` - -[#43781]: https://github.com/rust-lang/rust/issues/43781 -[#43348]: https://github.com/rust-lang/rust/issues/43348 diff --git a/src/test/ui/feature-gates/feature-gate-doc_cfg.rs b/src/test/ui/feature-gates/feature-gate-doc_cfg.rs deleted file mode 100644 index b12b8a105718..000000000000 --- a/src/test/ui/feature-gates/feature-gate-doc_cfg.rs +++ /dev/null @@ -1,2 +0,0 @@ -#[doc(cfg(unix))] //~ ERROR: `#[doc(cfg)]` is experimental -fn main() {} diff --git a/src/test/ui/feature-gates/feature-gate-doc_cfg.stderr b/src/test/ui/feature-gates/feature-gate-doc_cfg.stderr deleted file mode 100644 index fe88e08c1234..000000000000 --- a/src/test/ui/feature-gates/feature-gate-doc_cfg.stderr +++ /dev/null @@ -1,12 +0,0 @@ -error[E0658]: `#[doc(cfg)]` is experimental - --> $DIR/feature-gate-doc_cfg.rs:1:1 - | -LL | #[doc(cfg(unix))] - | ^^^^^^^^^^^^^^^^^ - | - = note: see issue #43781 for more information - = help: add `#![feature(doc_cfg)]` to the crate attributes to enable - -error: aborting due to previous error - -For more information about this error, try `rustc --explain E0658`.