Rollup merge of #53076 - QuietMisdreavus:cfg-rustdoc, r=GuillaumeGomez

set cfg(rustdoc) when rustdoc is running on a crate

When using `#[doc(cfg)]` to document platform-specific items, it's a little cumbersome to get all the platforms' items to appear all at once. For example, the standard library adds `--cfg dox` to rustdoc's command line whenever it builds docs, and the documentation for `#![feature(doc_cfg)]` suggests using a Cargo feature to approximate the same thing. This is a little awkward, because you always need to remember to set `--features dox` whenever you build documentation.

This PR proposes making rustdoc set `#[cfg(rustdoc)]` whenever it runs on a crate, to provide an officially-sanctioned version of this that is set automatically. This way, there's a standardized way to declare that a certain version of an item is specifically when building docs.

To try to prevent the spread of this feature from happening too quickly, this PR also restricts the use of this flag to whenever `#![feature(doc_cfg)]` is active. I'm sure there are other uses for this, but right now i'm tying it to this feature. (If it makes more sense to give this its own feature, i can easily do that.)

Author: kennytm

src/bootstrap/bin/rustdoc.rs

@@ -37,6 +37,8 @@ fn main() {
     let mut dylib_path = bootstrap::util::dylib_path();
     dylib_path.insert(0, PathBuf::from(libdir.clone()));
 
+    //FIXME(misdreavus): once stdsimd uses cfg(rustdoc) instead of cfg(dox), remove the `--cfg dox`
+    //arguments here
     let mut cmd = Command::new(rustdoc);
     cmd.args(&args)
         .arg("--cfg")

src/doc/rustdoc/src/unstable-features.md

@@ -106,27 +106,25 @@ The `#[doc(cfg(...))]` attribute has another effect: When Rustdoc renders docume
 item, it will be accompanied by a banner explaining that the item is only available on certain
 platforms.
 
-As mentioned earlier, getting the items to Rustdoc requires some extra preparation. The standard
-library adds a `--cfg dox` flag to every Rustdoc command, but the same thing can be accomplished by
-adding a feature to your Cargo.toml and adding `--feature dox` (or whatever you choose to name the
-feature) to your `cargo doc` calls.
+For Rustdoc to document an item, it needs to see it, regardless of what platform it's currently
+running on. To aid this, Rustdoc sets the flag `#[cfg(rustdoc)]` when running on your crate.
+Combining this with the target platform of a given item allows it to appear when building your crate
+normally on that platform, as well as when building documentation anywhere.
 
-Either way, once you create an environment for the documentation, you can start to augment your
-`#[cfg]` attributes to allow both the target platform *and* the documentation configuration to leave
-the item in. For example, `#[cfg(any(windows, feature = "dox"))]` 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:
+For example, `#[cfg(any(windows, rustdoc))]` 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, feature = "dox"))]
+#[cfg(any(windows, rustdoc))]
 #[doc(cfg(windows))]
 pub struct WindowsToken;
 
 /// Token struct that can only be used on Unix.
-#[cfg(any(unix, feature = "dox"))]
+#[cfg(any(unix, rustdoc))]
 #[doc(cfg(unix))]
 pub struct UnixToken;
 ```

src/doc/unstable-book/src/language-features/doc-cfg.md

@@ -12,13 +12,17 @@ This attribute has two effects:
 
 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(rustdoc)]`, 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, feature = "documentation"))]
+#[cfg(any(windows, rustdoc))]
 #[doc(cfg(windows))]
 /// The application's icon in the notification area (a.k.a. system tray).
 ///
@@ -39,4 +43,4 @@ pub struct Icon {
 ```
 
 [#43781]: https://github.com/rust-lang/rust/issues/43781
-[#43348]: https://github.com/rust-lang/rust/issues/43348
+[#43348]: https://github.com/rust-lang/rust/issues/43348

src/libcore/macros.rs

@@ -541,7 +541,7 @@ macro_rules! unimplemented {
 /// into libsyntax itself.
 ///
 /// For more information, see documentation for `std`'s macros.
-#[cfg(dox)]
+#[cfg(rustdoc)]
 mod builtin {
 
     /// Unconditionally causes compilation to fail with the given error message when encountered.

src/librustdoc/lib.rs

@@ -477,7 +477,8 @@ fn main_args(args: &[String]) -> isize {
 
     let output = matches.opt_str("o").map(|s| PathBuf::from(&s));
     let css_file_extension = matches.opt_str("e").map(|s| PathBuf::from(&s));
-    let cfgs = matches.opt_strs("cfg");
+    let mut cfgs = matches.opt_strs("cfg");
+    cfgs.push("rustdoc".to_string());
 
     if let Some(ref p) = css_file_extension {
         if !p.is_file() {
@@ -671,7 +672,8 @@ where R: 'static + Send,
     for s in &matches.opt_strs("L") {
         paths.add_path(s, ErrorOutputType::default());
     }
-    let cfgs = matches.opt_strs("cfg");
+    let mut cfgs = matches.opt_strs("cfg");
+    cfgs.push("rustdoc".to_string());
     let triple = matches.opt_str("target").map(|target| {
         if target.ends_with(".json") {
             TargetTriple::TargetPath(PathBuf::from(target))

src/libstd/macros.rs

@@ -309,7 +309,7 @@ macro_rules! assert_approx_eq {
 /// These macros do not have any corresponding definition with a `macro_rules!`
 /// macro, but are documented here. Their implementations can be found hardcoded
 /// into libsyntax itself.
-#[cfg(dox)]
+#[cfg(rustdoc)]
 mod builtin {
 
     /// Unconditionally causes compilation to fail with the given error message when encountered.

src/libstd/os/mod.rs

@@ -14,7 +14,7 @@
 #![allow(missing_docs, nonstandard_style, missing_debug_implementations)]
 
 cfg_if! {
-    if #[cfg(dox)] {
+    if #[cfg(rustdoc)] {
 
         // When documenting libstd we want to show unix/windows/linux modules as
         // these are the "main modules" that are used across platforms. This

src/libstd/sys/mod.rs

@@ -57,7 +57,7 @@ cfg_if! {
 // then later used in the `std::os` module when documenting, for example,
 // Windows when we're compiling for Linux.
 
-#[cfg(dox)]
+#[cfg(rustdoc)]
 cfg_if! {
     if #[cfg(any(unix, target_os = "redox"))] {
         // On unix we'll document what's already available
@@ -77,7 +77,7 @@ cfg_if! {
     }
 }
 
-#[cfg(dox)]
+#[cfg(rustdoc)]
 cfg_if! {
     if #[cfg(windows)] {
         // On windows we'll just be documenting what's already available

src/libstd/sys/unix/mod.rs

@@ -13,22 +13,22 @@
 use io::{self, ErrorKind};
 use libc;
 
-#[cfg(any(dox, target_os = "linux"))] pub use os::linux as platform;
-
-#[cfg(all(not(dox), target_os = "android"))]   pub use os::android as platform;
-#[cfg(all(not(dox), target_os = "bitrig"))]    pub use os::bitrig as platform;
-#[cfg(all(not(dox), target_os = "dragonfly"))] pub use os::dragonfly as platform;
-#[cfg(all(not(dox), target_os = "freebsd"))]   pub use os::freebsd as platform;
-#[cfg(all(not(dox), target_os = "haiku"))]     pub use os::haiku as platform;
-#[cfg(all(not(dox), target_os = "ios"))]       pub use os::ios as platform;
-#[cfg(all(not(dox), target_os = "macos"))]     pub use os::macos as platform;
-#[cfg(all(not(dox), target_os = "netbsd"))]    pub use os::netbsd as platform;
-#[cfg(all(not(dox), target_os = "openbsd"))]   pub use os::openbsd as platform;
-#[cfg(all(not(dox), target_os = "solaris"))]   pub use os::solaris as platform;
-#[cfg(all(not(dox), target_os = "emscripten"))] pub use os::emscripten as platform;
-#[cfg(all(not(dox), target_os = "fuchsia"))]   pub use os::fuchsia as platform;
-#[cfg(all(not(dox), target_os = "l4re"))]      pub use os::linux as platform;
-#[cfg(all(not(dox), target_os = "hermit"))]    pub use os::hermit as platform;
+#[cfg(any(rustdoc, target_os = "linux"))] pub use os::linux as platform;
+
+#[cfg(all(not(rustdoc), target_os = "android"))]   pub use os::android as platform;
+#[cfg(all(not(rustdoc), target_os = "bitrig"))]    pub use os::bitrig as platform;
+#[cfg(all(not(rustdoc), target_os = "dragonfly"))] pub use os::dragonfly as platform;
+#[cfg(all(not(rustdoc), target_os = "freebsd"))]   pub use os::freebsd as platform;
+#[cfg(all(not(rustdoc), target_os = "haiku"))]     pub use os::haiku as platform;
+#[cfg(all(not(rustdoc), target_os = "ios"))]       pub use os::ios as platform;
+#[cfg(all(not(rustdoc), target_os = "macos"))]     pub use os::macos as platform;
+#[cfg(all(not(rustdoc), target_os = "netbsd"))]    pub use os::netbsd as platform;
+#[cfg(all(not(rustdoc), target_os = "openbsd"))]   pub use os::openbsd as platform;
+#[cfg(all(not(rustdoc), target_os = "solaris"))]   pub use os::solaris as platform;
+#[cfg(all(not(rustdoc), target_os = "emscripten"))] pub use os::emscripten as platform;
+#[cfg(all(not(rustdoc), target_os = "fuchsia"))]   pub use os::fuchsia as platform;
+#[cfg(all(not(rustdoc), target_os = "l4re"))]      pub use os::linux as platform;
+#[cfg(all(not(rustdoc), target_os = "hermit"))]    pub use os::hermit as platform;
 
 pub use self::rand::hashmap_random_keys;
 pub use libc::strlen;

src/libstd/sys/windows/c.rs

@@ -794,7 +794,7 @@ pub struct FLOATING_SAVE_AREA {
 // will not appear in the final documentation. This should be also defined for
 // other architectures supported by Windows such as ARM, and for historical
 // interest, maybe MIPS and PowerPC as well.
-#[cfg(all(dox, not(any(target_arch = "x86_64", target_arch = "x86", target_arch = "aarch64"))))]
+#[cfg(all(rustdoc, not(any(target_arch = "x86_64", target_arch = "x86", target_arch = "aarch64"))))]
 pub enum CONTEXT {}
 
 #[cfg(target_arch = "aarch64")]

src/libsyntax/feature_gate.rs

@@ -1151,6 +1151,7 @@ const GATED_CFGS: &[(&str, &str, fn(&Features) -> bool)] = &[
     ("target_vendor", "cfg_target_vendor", cfg_fn!(cfg_target_vendor)),
     ("target_thread_local", "cfg_target_thread_local", cfg_fn!(cfg_target_thread_local)),
     ("target_has_atomic", "cfg_target_has_atomic", cfg_fn!(cfg_target_has_atomic)),
+    ("rustdoc", "doc_cfg", cfg_fn!(doc_cfg)),
 ];
 
 #[derive(Debug)]

src/test/ui/feature-gate-doc_cfg-cfg-rustdoc.rs

@@ -0,0 +1,14 @@
+// Copyright 2018 The Rust Project Developers. See the COPYRIGHT
+// file at the top-level directory of this distribution and at
+// http://rust-lang.org/COPYRIGHT.
+//
+// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
+// option. This file may not be copied, modified, or distributed
+// except according to those terms.
+
+#[cfg(rustdoc)] //~ ERROR: `cfg(rustdoc)` is experimental and subject to change
+pub struct SomeStruct;
+
+fn main() {}

src/test/ui/feature-gate-doc_cfg-cfg-rustdoc.stderr

@@ -0,0 +1,11 @@
+error[E0658]: `cfg(rustdoc)` is experimental and subject to change (see issue #43781)
+  --> $DIR/feature-gate-doc_cfg-cfg-rustdoc.rs:11:7
+   |
+LL | #[cfg(rustdoc)] //~ ERROR: `cfg(rustdoc)` is experimental and subject to change
+   |       ^^^^^^^
+   |
+   = 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`.