add feature gate doc_masked and tests

diff --git a/src/doc/unstable-book/src/language-features/doc-masked.md b/src/doc/unstable-book/src/language-features/doc-masked.md
new file mode 100644 (file)
index 0000000..0d0a46c
--- /dev/null
+++ b/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 { }
+```

diff --git a/src/libstd/lib.rs b/src/libstd/lib.rs
index 6fa4a8738ac7bd00d4dea5e4a66a2c9ec1d59b7c..41fb5bc684afc6f70a089bd3f98e0928b062e5d0 100644 (file)
--- a/src/libstd/lib.rs
+++ b/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]

diff --git a/src/libsyntax/feature_gate.rs b/src/libsyntax/feature_gate.rs
index 54d41a030fd77ad38f3f7b6938df868c64e3b606..9dad92bb18bbe14e675b537d1a0b6cb6055709fd 100644 (file)
--- a/src/libsyntax/feature_gate.rs
+++ b/src/libsyntax/feature_gate.rs
@@ -376,6 +376,8 @@ pub fn new() -> 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 @@ fn visit_attribute(&mut self, attr: &ast::Attribute) {
                     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"
+                    );
                 }
             }
         }

diff --git a/src/test/compile-fail/feature-gate-doc_masked.rs b/src/test/compile-fail/feature-gate-doc_masked.rs
new file mode 100644 (file)
index 0000000..bb5be9d
--- /dev/null
+++ b/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() {}

diff --git a/src/test/rustdoc/doc-masked.rs b/src/test/rustdoc/doc-masked.rs
new file mode 100644 (file)
index 0000000..78d3202
--- /dev/null
+++ b/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 { }