From: QuietMisdreavus Date: Thu, 5 Oct 2017 03:00:22 +0000 (-0500) Subject: add doc_highlight feature flag and tests X-Git-Url: https://git.lizzy.rs/?a=commitdiff_plain;h=831fd783416d9f87ec9308ed56e891d0b1ffdbcd;p=rust.git add doc_highlight feature flag and tests --- diff --git a/src/doc/unstable-book/src/language-features/doc-spotlight.md b/src/doc/unstable-book/src/language-features/doc-spotlight.md new file mode 100644 index 00000000000..8aca01bb638 --- /dev/null +++ b/src/doc/unstable-book/src/language-features/doc-spotlight.md @@ -0,0 +1,27 @@ +# `doc_spotlight` + +The tracking issue for this feature is: [TODO] + +The `doc_spotlight` feature allows the use of the `spotlight` parameter to the `#[doc]` attribute, +to "spotlight" a specific trait on the return values of functions. Adding a `#[doc(spotlight)]` +attribute to a trait definition will make rustdoc print extra information for functions which return +a type that implements that trait. This attribute is applied to the `Iterator`, `io::Read`, and +`io::Write` traits in the standard library. + +You can do this on your own traits, like this: + +``` +#![feature(doc_spotlight)] + +#[doc(spotlight)] +pub trait MyTrait {} + +pub struct MyStruct; +impl MyTrait for MyStruct {} + +/// The docs for this function will have an extra line about `MyStruct` implementing `MyTrait`, +/// without having to write that yourself! +pub fn my_fn() -> MyStruct { MyStruct } +``` + +This feature was originally implemented in PR [TODO]. diff --git a/src/libcore/lib.rs b/src/libcore/lib.rs index 4a57417e86a..631b9f98589 100644 --- a/src/libcore/lib.rs +++ b/src/libcore/lib.rs @@ -107,6 +107,24 @@ #![feature(const_unsafe_cell_new)] #![feature(const_cell_new)] #![feature(const_nonzero_new)] +#![cfg_attr(not(stage0), feature(doc_spotlight))] + +#![cfg_attr(not(stage0), feature(const_min_value))] +#![cfg_attr(not(stage0), feature(const_max_value))] +#![cfg_attr(not(stage0), feature(const_atomic_bool_new))] +#![cfg_attr(not(stage0), feature(const_atomic_isize_new))] +#![cfg_attr(not(stage0), feature(const_atomic_usize_new))] +#![cfg_attr(not(stage0), feature(const_atomic_i8_new))] +#![cfg_attr(not(stage0), feature(const_atomic_u8_new))] +#![cfg_attr(not(stage0), feature(const_atomic_i16_new))] +#![cfg_attr(not(stage0), feature(const_atomic_u16_new))] +#![cfg_attr(not(stage0), feature(const_atomic_i32_new))] +#![cfg_attr(not(stage0), feature(const_atomic_u32_new))] +#![cfg_attr(not(stage0), feature(const_atomic_i64_new))] +#![cfg_attr(not(stage0), feature(const_atomic_u64_new))] +#![cfg_attr(not(stage0), feature(const_unsafe_cell_new))] +#![cfg_attr(not(stage0), feature(const_cell_new))] +#![cfg_attr(not(stage0), feature(const_nonzero_new))] #[prelude_import] #[allow(unused)] diff --git a/src/libstd/lib.rs b/src/libstd/lib.rs index 37cc7a49b52..ccc89ccdcf4 100644 --- a/src/libstd/lib.rs +++ b/src/libstd/lib.rs @@ -329,6 +329,7 @@ #![feature(vec_push_all)] #![feature(doc_cfg)] #![feature(doc_masked)] +#![feature(doc_spotlight)] #![cfg_attr(test, feature(update_panic_count))] #![cfg_attr(windows, feature(const_atomic_ptr_new))] diff --git a/src/libsyntax/feature_gate.rs b/src/libsyntax/feature_gate.rs index 97eec3a21e9..9bfb3bdbdb4 100644 --- a/src/libsyntax/feature_gate.rs +++ b/src/libsyntax/feature_gate.rs @@ -381,6 +381,8 @@ pub fn new() -> Features { (active, doc_cfg, "1.21.0", Some(43781)), // #[doc(masked)] (active, doc_masked, "1.21.0", Some(44027)), + // #[doc(spotlight)] + (active, doc_spotlight, "1.22.0", None), // allow `#[must_use]` on functions and comparison operators (RFC 1940) (active, fn_must_use, "1.21.0", Some(43302)), @@ -1292,6 +1294,10 @@ fn visit_attribute(&mut self, attr: &ast::Attribute) { gate_feature_post!(&self, doc_masked, attr.span, "#[doc(masked)] is experimental" ); + } else if content.iter().any(|c| c.check_name("spotlight")) { + gate_feature_post!(&self, doc_spotlight, attr.span, + "#[doc(spotlight)] is experimental" + ); } } } diff --git a/src/test/compile-fail/feature-gate-doc_spotlight.rs b/src/test/compile-fail/feature-gate-doc_spotlight.rs new file mode 100644 index 00000000000..6369358538d --- /dev/null +++ b/src/test/compile-fail/feature-gate-doc_spotlight.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(spotlight)] //~ ERROR: #[doc(spotlight)] is experimental +trait SomeTrait {} + +fn main() {} diff --git a/src/test/rustdoc/doc-spotlight.rs b/src/test/rustdoc/doc-spotlight.rs new file mode 100644 index 00000000000..eb05b261fcc --- /dev/null +++ b/src/test/rustdoc/doc-spotlight.rs @@ -0,0 +1,46 @@ +// 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_spotlight)] + +pub struct Wrapper { + inner: T, +} + +impl SomeTrait for Wrapper {} + +#[doc(spotlight)] +pub trait SomeTrait { + // @has doc_spotlight/trait.SomeTrait.html + // @has - '//code[@class="spotlight"]' 'impl SomeTrait for Wrapper' + fn wrap_me(self) -> Wrapper where Self: Sized { + Wrapper { + inner: self, + } + } +} + +pub struct SomeStruct; +impl SomeTrait for SomeStruct {} + +impl SomeStruct { + // @has doc_spotlight/struct.SomeStruct.html + // @has - '//code[@class="spotlight"]' 'impl SomeTrait for SomeStruct' + // @has - '//code[@class="spotlight"]' 'impl SomeTrait for Wrapper' + pub fn new() -> SomeStruct { + SomeStruct + } +} + +// @has doc_spotlight/fn.bare_fn.html +// @has - '//code[@class="spotlight"]' 'impl SomeTrait for SomeStruct' +pub fn bare_fn() -> SomeStruct { + SomeStruct +}