add feature gate doc_masked and tests

Author: QuietMisdreavus

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

@@ -0,0 +1,37 @@
+# `doc_masked`
+
+The tracking issue for this feature is: [TODO](TODO)
+
+-----
+
+The `doc_masked` feature allows a crate to exclude types from a given crate from appearing in lists
+of trait implementations. The specifics of the feature are as follows:
+
+1. When rustdoc encounters an `extern crate` statement annotated with a `#[doc(masked)]` attribute,
+   it marks the crate as being masked.
+
+2. When listing traits a given type implements, rustdoc ensures that traits from masked crates are
+   not emitted into the documentation.
+
+3. When listing types that implement a given trait, rustdoc ensures that types from masked crates
+   are not emitted into the documentation.
+
+This feature was introduced in PR [TODO](TODO) to ensure that compiler-internal and
+implementation-specific types and traits were not included in the standard library's documentation.
+Such types would introduce broken links into the documentation.
+
+```rust
+#![feature(doc_masked)]
+
+// Since std is automatically imported, we need to import it into a separate name to apply the
+// attribute. This is used as a simple demonstration, but any extern crate statement will suffice.
+#[doc(masked)]
+extern crate std as realstd;
+
+/// A sample marker trait that exists on floating-point numbers, even though this page won't list
+/// them!
+pub trait MyMarker { }
+
+impl MyMarker for f32 { }
+impl MyMarker for f64 { }
+```

src/libstd/lib.rs

@@ -313,6 +313,7 @@
 #![feature(unwind_attributes)]
 #![feature(vec_push_all)]
 #![feature(doc_cfg)]
+#![feature(doc_masked)]
 #![cfg_attr(test, feature(update_panic_count))]
 
 #![default_lib_allocator]

src/libsyntax/feature_gate.rs

@@ -376,6 +376,8 @@ declare_features! (
 
     // #[doc(cfg(...))]
     (active, doc_cfg, "1.21.0", Some(43781)),
+    // #[doc(masked)]
+    (active, doc_masked, "1.21.0", None),
 
     // allow `#[must_use]` on functions (RFC 1940)
     (active, fn_must_use, "1.21.0", Some(43302)),
@@ -1229,6 +1231,10 @@ impl<'a> Visitor<'a> for PostExpansionVisitor<'a> {
                     gate_feature_post!(&self, doc_cfg, attr.span,
                         "#[doc(cfg(...))] is experimental"
                     );
+                } else if content.iter().any(|c| c.check_name("masked")) {
+                    gate_feature_post!(&self, doc_masked, attr.span,
+                        "#[doc(masked)] is experimental"
+                    );
                 }
             }
         }

src/test/compile-fail/feature-gate-doc_masked.rs

@@ -0,0 +1,14 @@
+// Copyright 2017 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.
+
+#[doc(masked)] //~ ERROR: #[doc(masked)] is experimental
+extern crate std as realstd;
+
+fn main() {}

src/test/rustdoc/doc-masked.rs

@@ -0,0 +1,29 @@
+// Copyright 2017 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.
+
+#![feature(doc_masked)]
+
+#![doc(masked)]
+extern crate std as realstd;
+
+// @has doc_masked/struct.LocalStruct.html
+// @has - '//*[@class="impl"]//code' 'impl LocalTrait for LocalStruct'
+// @!has - '//*[@class="impl"]//code' 'impl Copy for LocalStruct'
+#[derive(Copy, Clone)]
+pub struct LocalStruct;
+
+// @has doc_masked/trait.LocalTrait.html
+// @has - '//*[@id="implementors-list"]//code' 'impl LocalTrait for LocalStruct'
+// @!has - '//*[@id="implementors-list"]//code' 'impl LocalTrait for usize'
+pub trait LocalTrait { }
+
+impl LocalTrait for LocalStruct { }
+
+impl LocalTrait for usize { }