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 index 00000000000..0d0a46ce9ee --- /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 6fa4a8738ac..41fb5bc684a 100644 --- 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 54d41a030fd..9dad92bb18b 100644 --- a/src/libsyntax/feature_gate.rs +++ b/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" + ); } } } 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 index 00000000000..bb5be9d6971 --- /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 or the MIT license +// , 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 index 00000000000..78d32028e36 --- /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 or the MIT license +// , 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 { }