--- /dev/null
+# `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].
#![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)]
#![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))]
(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)),
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"
+ );
}
}
}
--- /dev/null
+// 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(spotlight)] //~ ERROR: #[doc(spotlight)] is experimental
+trait SomeTrait {}
+
+fn main() {}
--- /dev/null
+// 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_spotlight)]
+
+pub struct Wrapper<T> {
+ inner: T,
+}
+
+impl<T: SomeTrait> SomeTrait for Wrapper<T> {}
+
+#[doc(spotlight)]
+pub trait SomeTrait {
+ // @has doc_spotlight/trait.SomeTrait.html
+ // @has - '//code[@class="spotlight"]' 'impl<T: SomeTrait> SomeTrait for Wrapper<T>'
+ fn wrap_me(self) -> Wrapper<Self> 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<T: SomeTrait> SomeTrait for Wrapper<T>'
+ 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
+}