Skip to content

Commit 831fd78

Browse files
QuietMisdreavusGuillaumeGomez
authored andcommitted
add doc_highlight feature flag and tests
1 parent cbe4ac3 commit 831fd78

File tree

6 files changed

+112
-0
lines changed

6 files changed

+112
-0
lines changed
Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# `doc_spotlight`
2+
3+
The tracking issue for this feature is: [TODO]
4+
5+
The `doc_spotlight` feature allows the use of the `spotlight` parameter to the `#[doc]` attribute,
6+
to "spotlight" a specific trait on the return values of functions. Adding a `#[doc(spotlight)]`
7+
attribute to a trait definition will make rustdoc print extra information for functions which return
8+
a type that implements that trait. This attribute is applied to the `Iterator`, `io::Read`, and
9+
`io::Write` traits in the standard library.
10+
11+
You can do this on your own traits, like this:
12+
13+
```
14+
#![feature(doc_spotlight)]
15+
16+
#[doc(spotlight)]
17+
pub trait MyTrait {}
18+
19+
pub struct MyStruct;
20+
impl MyTrait for MyStruct {}
21+
22+
/// The docs for this function will have an extra line about `MyStruct` implementing `MyTrait`,
23+
/// without having to write that yourself!
24+
pub fn my_fn() -> MyStruct { MyStruct }
25+
```
26+
27+
This feature was originally implemented in PR [TODO].

src/libcore/lib.rs

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -107,6 +107,24 @@
107107
#![feature(const_unsafe_cell_new)]
108108
#![feature(const_cell_new)]
109109
#![feature(const_nonzero_new)]
110+
#![cfg_attr(not(stage0), feature(doc_spotlight))]
111+
112+
#![cfg_attr(not(stage0), feature(const_min_value))]
113+
#![cfg_attr(not(stage0), feature(const_max_value))]
114+
#![cfg_attr(not(stage0), feature(const_atomic_bool_new))]
115+
#![cfg_attr(not(stage0), feature(const_atomic_isize_new))]
116+
#![cfg_attr(not(stage0), feature(const_atomic_usize_new))]
117+
#![cfg_attr(not(stage0), feature(const_atomic_i8_new))]
118+
#![cfg_attr(not(stage0), feature(const_atomic_u8_new))]
119+
#![cfg_attr(not(stage0), feature(const_atomic_i16_new))]
120+
#![cfg_attr(not(stage0), feature(const_atomic_u16_new))]
121+
#![cfg_attr(not(stage0), feature(const_atomic_i32_new))]
122+
#![cfg_attr(not(stage0), feature(const_atomic_u32_new))]
123+
#![cfg_attr(not(stage0), feature(const_atomic_i64_new))]
124+
#![cfg_attr(not(stage0), feature(const_atomic_u64_new))]
125+
#![cfg_attr(not(stage0), feature(const_unsafe_cell_new))]
126+
#![cfg_attr(not(stage0), feature(const_cell_new))]
127+
#![cfg_attr(not(stage0), feature(const_nonzero_new))]
110128

111129
#[prelude_import]
112130
#[allow(unused)]

src/libstd/lib.rs

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -329,6 +329,7 @@
329329
#![feature(vec_push_all)]
330330
#![feature(doc_cfg)]
331331
#![feature(doc_masked)]
332+
#![feature(doc_spotlight)]
332333
#![cfg_attr(test, feature(update_panic_count))]
333334
#![cfg_attr(windows, feature(const_atomic_ptr_new))]
334335

src/libsyntax/feature_gate.rs

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -381,6 +381,8 @@ declare_features! (
381381
(active, doc_cfg, "1.21.0", Some(43781)),
382382
// #[doc(masked)]
383383
(active, doc_masked, "1.21.0", Some(44027)),
384+
// #[doc(spotlight)]
385+
(active, doc_spotlight, "1.22.0", None),
384386

385387
// allow `#[must_use]` on functions and comparison operators (RFC 1940)
386388
(active, fn_must_use, "1.21.0", Some(43302)),
@@ -1292,6 +1294,10 @@ impl<'a> Visitor<'a> for PostExpansionVisitor<'a> {
12921294
gate_feature_post!(&self, doc_masked, attr.span,
12931295
"#[doc(masked)] is experimental"
12941296
);
1297+
} else if content.iter().any(|c| c.check_name("spotlight")) {
1298+
gate_feature_post!(&self, doc_spotlight, attr.span,
1299+
"#[doc(spotlight)] is experimental"
1300+
);
12951301
}
12961302
}
12971303
}
Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
// Copyright 2017 The Rust Project Developers. See the COPYRIGHT
2+
// file at the top-level directory of this distribution and at
3+
// http://rust-lang.org/COPYRIGHT.
4+
//
5+
// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
6+
// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
7+
// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
8+
// option. This file may not be copied, modified, or distributed
9+
// except according to those terms.
10+
11+
#[doc(spotlight)] //~ ERROR: #[doc(spotlight)] is experimental
12+
trait SomeTrait {}
13+
14+
fn main() {}

src/test/rustdoc/doc-spotlight.rs

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
// Copyright 2017 The Rust Project Developers. See the COPYRIGHT
2+
// file at the top-level directory of this distribution and at
3+
// http://rust-lang.org/COPYRIGHT.
4+
//
5+
// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
6+
// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
7+
// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
8+
// option. This file may not be copied, modified, or distributed
9+
// except according to those terms.
10+
11+
#![feature(doc_spotlight)]
12+
13+
pub struct Wrapper<T> {
14+
inner: T,
15+
}
16+
17+
impl<T: SomeTrait> SomeTrait for Wrapper<T> {}
18+
19+
#[doc(spotlight)]
20+
pub trait SomeTrait {
21+
// @has doc_spotlight/trait.SomeTrait.html
22+
// @has - '//code[@class="spotlight"]' 'impl<T: SomeTrait> SomeTrait for Wrapper<T>'
23+
fn wrap_me(self) -> Wrapper<Self> where Self: Sized {
24+
Wrapper {
25+
inner: self,
26+
}
27+
}
28+
}
29+
30+
pub struct SomeStruct;
31+
impl SomeTrait for SomeStruct {}
32+
33+
impl SomeStruct {
34+
// @has doc_spotlight/struct.SomeStruct.html
35+
// @has - '//code[@class="spotlight"]' 'impl SomeTrait for SomeStruct'
36+
// @has - '//code[@class="spotlight"]' 'impl<T: SomeTrait> SomeTrait for Wrapper<T>'
37+
pub fn new() -> SomeStruct {
38+
SomeStruct
39+
}
40+
}
41+
42+
// @has doc_spotlight/fn.bare_fn.html
43+
// @has - '//code[@class="spotlight"]' 'impl SomeTrait for SomeStruct'
44+
pub fn bare_fn() -> SomeStruct {
45+
SomeStruct
46+
}

0 commit comments

Comments
 (0)