nordic-dev.net/rust
nordic-dev.net/rust
2
0
Fork 0
mirror of https://github.com/rust-lang/rust.git synced 2024-11-01 15:01:51 +00:00
Code Issues Packages Projects Releases Wiki Activity

Rename #[doc(spotlight)] to #[doc(notable_trait)]

Browse Source 
"spotlight" is not a very specific or self-explaining name.
Additionally, the dialog that it triggers is called "Notable traits".
So, "notable trait" is a better name.

* Rename `#[doc(spotlight)]` to `#[doc(notable_trait)]`
* Rename `#![feature(doc_spotlight)]` to `#![feature(doc_notable_trait)]`
* Update documentation
* Improve documentation
This commit is contained in:
Camelid 2021-03-08 19:35:53 -08:00
parent 2ccf06302c
commit 34c6cee397
23 changed files with 149 additions and 84 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
compiler/rustc_ast_passes/src/feature_gate.rs
View File

@ -313,7 +313,7 @@ impl<'a> Visitor<'a> for PostExpansionVisitor<'a> {
include => external_doc
cfg => doc_cfg
masked => doc_masked
spotlight => doc_spotlight
notable_trait => doc_notable_trait
keyword => doc_keyword
);
}

7
compiler/rustc_feature/src/active.rs
View File

@ -216,6 +216,10 @@ declare_features! (
/// Renamed from `optin_builtin_traits`.
(active, auto_traits, "1.50.0", Some(13231), None),
/// Allows `#[doc(notable_trait)]`.
/// Renamed from `doc_spotlight`.
(active, doc_notable_trait, "1.52.0", Some(45040), None),
// no-tracking-issue-end
// -------------------------------------------------------------------------
@ -374,9 +378,6 @@ declare_features! (
/// Allows `#[doc(masked)]`.
(active, doc_masked, "1.21.0", Some(44027), None),
/// Allows `#[doc(spotlight)]`.
(active, doc_spotlight, "1.22.0", Some(45040), None),
/// Allows `#[doc(include = "some-file")]`.
(active, external_doc, "1.22.0", Some(44732), None),

5
compiler/rustc_feature/src/removed.rs
View File

@ -80,6 +80,11 @@ declare_features! (
Some("subsumed by `#![feature(allocator_internals)]`")),
/// Allows identifying crates that contain sanitizer runtimes.
(removed, sanitizer_runtime, "1.17.0", None, None, None),
/// Allows `#[doc(spotlight)]`.
/// The attribute was renamed to `#[doc(notable_trait)]`
/// and the feature to `doc_notable_trait`.
(removed, doc_spotlight, "1.22.0", Some(45040), None,
Some("renamed to `doc_notable_trait`")),
(removed, proc_macro_mod, "1.27.0", Some(54727), None,
Some("subsumed by `#![feature(proc_macro_hygiene)]`")),
(removed, proc_macro_expr, "1.27.0", Some(54727), None,

22
compiler/rustc_passes/src/check_attr.rs
View File

@ -9,7 +9,7 @@ use rustc_middle::ty::query::Providers;
use rustc_middle::ty::TyCtxt;
use rustc_ast::{Attribute, Lit, LitKind, NestedMetaItem};
use rustc_errors::{pluralize, struct_span_err};
use rustc_errors::{pluralize, struct_span_err, Applicability};
use rustc_hir as hir;
use rustc_hir::def_id::LocalDefId;
use rustc_hir::intravisit::{self, NestedVisitorMap, Visitor};
@ -589,10 +589,10 @@ impl CheckAttrVisitor<'tcx> {
| sym::masked
| sym::no_default_passes
| sym::no_inline
| sym::notable_trait
| sym::passes
| sym::plugins
| sym::primitive
| sym::spotlight
| sym::test => {}
_ => {
@ -601,11 +601,23 @@ impl CheckAttrVisitor<'tcx> {
hir_id,
i_meta.span,
|lint| {
let msg = format!(
let mut diag = lint.build(&format!(
"unknown `doc` attribute `{}`",
rustc_ast_pretty::pprust::path_to_string(&i_meta.path),
);
lint.build(&msg).emit();
));
if i_meta.has_name(sym::spotlight) {
diag.note(
"`doc(spotlight)` was renamed to `doc(notable_trait)`",
);
diag.span_suggestion_short(
i_meta.span,
"use `notable_trait` instead",
String::from("notable_trait"),
Applicability::MachineApplicable,
);
diag.note("`doc(spotlight)` is now a no-op");
}
diag.emit();
},
);
is_valid = false;

2
compiler/rustc_span/src/symbol.rs
View File

@ -476,6 +476,7 @@ symbols! {
doc_cfg,
doc_keyword,
doc_masked,
doc_notable_trait,
doc_spotlight,
doctest,
document_private_items,
@ -799,6 +800,7 @@ symbols! {
noreturn,
nostack,
not,
notable_trait,
note,
object_safe_for_dispatch,
of,

3
library/core/src/future/future.rs
View File

@ -24,7 +24,8 @@ use crate::task::{Context, Poll};
/// `.await` the value.
///
/// [`Waker`]: crate::task::Waker
#[doc(spotlight)]
#[cfg_attr(bootstrap, doc(spotlight))]
#[cfg_attr(not(bootstrap), doc(notable_trait))]
#[must_use = "futures do nothing unless you `.await` or poll them"]
#[stable(feature = "futures_api", since = "1.36.0")]
#[lang = "future_trait"]

3
library/core/src/iter/traits/iterator.rs
View File

@ -92,7 +92,8 @@ fn _assert_is_object_safe(_: &dyn Iterator<Item = ()>) {}
label = "`{Self}` is not an iterator",
message = "`{Self}` is not an iterator"
)]
#[doc(spotlight)]
#[cfg_attr(bootstrap, doc(spotlight))]
#[cfg_attr(not(bootstrap), doc(notable_trait))]
#[rustc_diagnostic_item = "Iterator"]
#[must_use = "iterators are lazy and do nothing unless consumed"]
pub trait Iterator {

3
library/core/src/lib.rs
View File

@ -108,7 +108,8 @@
#![feature(custom_inner_attributes)]
#![feature(decl_macro)]
#![feature(doc_cfg)]
#![feature(doc_spotlight)]
#![cfg_attr(bootstrap, feature(doc_spotlight))]
#![cfg_attr(not(bootstrap), feature(doc_notable_trait))]
#![feature(duration_consts_2)]
#![feature(duration_saturating_ops)]
#![feature(extended_key_value_attributes)]

6
library/std/src/io/mod.rs
View File

@ -505,7 +505,8 @@ pub(crate) fn default_read_exact<R: Read + ?Sized>(this: &mut R, mut buf: &mut [
/// [`std::io`]: self
/// [`File`]: crate::fs::File
#[stable(feature = "rust1", since = "1.0.0")]
#[doc(spotlight)]
#[cfg_attr(bootstrap, doc(spotlight))]
#[cfg_attr(not(bootstrap), doc(notable_trait))]
pub trait Read {
/// Pull some bytes from this source into the specified buffer, returning
/// how many bytes were read.
@ -1291,7 +1292,8 @@ impl Initializer {
///
/// [`write_all`]: Write::write_all
#[stable(feature = "rust1", since = "1.0.0")]
#[doc(spotlight)]
#[cfg_attr(bootstrap, doc(spotlight))]
#[cfg_attr(not(bootstrap), doc(notable_trait))]
pub trait Write {
/// Write a buffer into this writer, returning how many bytes were written.
///

3
library/std/src/lib.rs
View File

@ -257,7 +257,8 @@
#![feature(doc_cfg)]
#![feature(doc_keyword)]
#![feature(doc_masked)]
#![feature(doc_spotlight)]
#![cfg_attr(bootstrap, feature(doc_spotlight))]
#![cfg_attr(not(bootstrap), feature(doc_notable_trait))]
#![feature(dropck_eyepatch)]
#![feature(duration_constants)]
#![feature(duration_zero)]

34
src/doc/rustdoc/src/unstable-features.md
View File

@ -88,26 +88,28 @@ Book][unstable-doc-cfg] and [its tracking issue][issue-doc-cfg].
[unstable-doc-cfg]: ../unstable-book/language-features/doc-cfg.html
[issue-doc-cfg]: https://github.com/rust-lang/rust/issues/43781
### Adding your trait to the "Important Traits" dialog
### Adding your trait to the "Notable traits" dialog
Rustdoc keeps a list of a few traits that are believed to be "fundamental" to a given type when
implemented on it. These traits are intended to be the primary interface for their types, and are
often the only thing available to be documented on their types. For this reason, Rustdoc will track
when a given type implements one of these traits and call special attention to it when a function
returns one of these types. This is the "Important Traits" dialog, visible as a circle-i button next
to the function, which, when clicked, shows the dialog.
Rustdoc keeps a list of a few traits that are believed to be "fundamental" to
types that implement them. These traits are intended to be the primary interface
for their implementers, and are often most of the API available to be documented
on their types. For this reason, Rustdoc will track when a given type implements
one of these traits and call special attention to it when a function returns one
of these types. This is the "Notable traits" dialog, accessible as a circled `i`
button next to the function, which, when clicked, shows the dialog.
In the standard library, the traits that qualify for inclusion are `Iterator`, `io::Read`, and
`io::Write`. However, rather than being implemented as a hard-coded list, these traits have a
special marker attribute on them: `#[doc(spotlight)]`. This means that you could apply this
attribute to your own trait to include it in the "Important Traits" dialog in documentation.
In the standard library, some of the traits that are part of this list are
`Iterator`, `Future`, `io::Read`, and `io::Write`. However, rather than being
implemented as a hard-coded list, these traits have a special marker attribute
on them: `#[doc(notable_trait)]`. This means that you can apply this attribute
to your own trait to include it in the "Notable traits" dialog in documentation.
The `#[doc(spotlight)]` attribute currently requires the `#![feature(doc_spotlight)]` feature gate.
For more information, see [its chapter in the Unstable Book][unstable-spotlight] and [its tracking
issue][issue-spotlight].
The `#[doc(notable_trait)]` attribute currently requires the `#![feature(doc_notable_trait)]`
feature gate. For more information, see [its chapter in the Unstable Book][unstable-notable_trait]
and [its tracking issue][issue-notable_trait].
[unstable-spotlight]: ../unstable-book/language-features/doc-spotlight.html
[issue-spotlight]: https://github.com/rust-lang/rust/issues/45040
[unstable-notable_trait]: ../unstable-book/language-features/doc-notable-trait.html
[issue-notable_trait]: https://github.com/rust-lang/rust/issues/45040
### Exclude certain dependencies from documentation

33
src/doc/unstable-book/src/language-features/doc-notable-trait.md Normal file
View File

@ -0,0 +1,33 @@
# `doc_notable_trait`
The tracking issue for this feature is: [#45040]
The `doc_notable_trait` feature allows the use of the `#[doc(notable_trait)]`
attribute, which will display the trait in a "Notable traits" dialog for
functions returning types that implement the trait. For example, this attribute
is applied to the `Iterator`, `Future`, `io::Read`, and `io::Write` traits in
the standard library.
You can do this on your own traits like so:
```
#![feature(doc_notable_trait)]
#[doc(notable_trait)]
pub trait MyTrait {}
pub struct MyStruct;
impl MyTrait for MyStruct {}
/// The docs for this function will have a button that displays a dialog about
/// `MyStruct` implementing `MyTrait`.
pub fn my_fn() -> MyStruct { MyStruct }
```
This feature was originally implemented in PR [#45039].
See also its documentation in [the rustdoc book][rustdoc-book-notable_trait].
[#45040]: https://github.com/rust-lang/rust/issues/45040
[#45039]: https://github.com/rust-lang/rust/pull/45039
[rustdoc-book-notable_trait]: ../../rustdoc/unstable-features.html#adding-your-trait-to-the-notable-traits-dialog

30
src/doc/unstable-book/src/language-features/doc-spotlight.md
View File

@ -1,30 +0,0 @@
# `doc_spotlight`
The tracking issue for this feature is: [#45040]
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. For example, this attribute is applied to the `Iterator`,
`io::Read`, `io::Write`, and `Future` 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 [#45039].
[#45040]: https://github.com/rust-lang/rust/issues/45040
[#45039]: https://github.com/rust-lang/rust/pull/45039

2
src/librustdoc/clean/inline.rs
View File

@ -628,7 +628,7 @@ crate fn record_extern_trait(cx: &mut DocContext<'_>, did: DefId) {
let trait_ = clean::TraitWithExtraInfo {
trait_,
is_spotlight: clean::utils::has_doc_flag(cx.tcx.get_attrs(did), sym::spotlight),
is_spotlight: clean::utils::has_doc_flag(cx.tcx.get_attrs(did), sym::notable_trait),
};
cx.external_traits.borrow_mut().insert(did, trait_);
cx.active_extern_traits.remove(&did);

2
src/librustdoc/formats/cache.rs
View File

@ -229,7 +229,7 @@ impl<'a, 'tcx> DocFolder for CacheBuilder<'a, 'tcx> {
if let clean::TraitItem(ref t) = *item.kind {
self.cache.traits.entry(item.def_id).or_insert_with(|| clean::TraitWithExtraInfo {
trait_: t.clone(),
is_spotlight: item.attrs.has_doc_flag(sym::spotlight),
is_spotlight: item.attrs.has_doc_flag(sym::notable_trait),
});
}

10
src/test/rustdoc-ui/doc-spotlight.fixed Normal file
View File

@ -0,0 +1,10 @@
// ignore-tidy-linelength
// check-pass
// run-rustfix
#![feature(doc_notable_trait)]
#[doc(notable_trait)]
//~^ WARN unknown `doc` attribute `spotlight`
//~| WARN this was previously accepted by the compiler but is being phased out; it will become a hard error in a future release!
trait MyTrait {}

10
src/test/rustdoc-ui/doc-spotlight.rs Normal file
View File

@ -0,0 +1,10 @@
// ignore-tidy-linelength
// check-pass
// run-rustfix
#![feature(doc_notable_trait)]
#[doc(spotlight)]
//~^ WARN unknown `doc` attribute `spotlight`
//~| WARN this was previously accepted by the compiler but is being phased out; it will become a hard error in a future release!
trait MyTrait {}

14
src/test/rustdoc-ui/doc-spotlight.stderr Normal file
View File

@ -0,0 +1,14 @@
warning: unknown `doc` attribute `spotlight`
--> $DIR/doc-spotlight.rs:7:7
|
LL | #[doc(spotlight)]
| ^^^^^^^^^ help: use `notable_trait` instead
|
= note: `#[warn(invalid_doc_attributes)]` on by default
= warning: this was previously accepted by the compiler but is being phased out; it will become a hard error in a future release!
= note: for more information, see issue #82730 <https://github.com/rust-lang/rust/issues/82730>
= note: `doc(spotlight)` was renamed to `doc(notable_trait)`
= note: `doc(spotlight)` is now a no-op
warning: 1 warning emitted

10
src/test/rustdoc/doc-spotlight.rs → src/test/rustdoc/doc-notable_trait.rs
View File

@ -1,4 +1,4 @@
#![feature(doc_spotlight)]
#![feature(doc_notable_trait)]
pub struct Wrapper<T> {
inner: T,
@ -6,9 +6,9 @@ pub struct Wrapper<T> {
impl<T: SomeTrait> SomeTrait for Wrapper<T> {}
#[doc(spotlight)]
#[doc(notable_trait)]
pub trait SomeTrait {
// @has doc_spotlight/trait.SomeTrait.html
// @has doc_notable_trait/trait.SomeTrait.html
// @has - '//code[@class="content"]' 'impl<T: SomeTrait> SomeTrait for Wrapper<T>'
fn wrap_me(self) -> Wrapper<Self> where Self: Sized {
Wrapper {
@ -21,7 +21,7 @@ pub struct SomeStruct;
impl SomeTrait for SomeStruct {}
impl SomeStruct {
// @has doc_spotlight/struct.SomeStruct.html
// @has doc_notable_trait/struct.SomeStruct.html
// @has - '//code[@class="content"]' 'impl SomeTrait for SomeStruct'
// @has - '//code[@class="content"]' 'impl<T: SomeTrait> SomeTrait for Wrapper<T>'
pub fn new() -> SomeStruct {
@ -29,7 +29,7 @@ impl SomeStruct {
}
}
// @has doc_spotlight/fn.bare_fn.html
// @has doc_notable_trait/fn.bare_fn.html
// @has - '//code[@class="content"]' 'impl SomeTrait for SomeStruct'
pub fn bare_fn() -> SomeStruct {
SomeStruct

4
src/test/ui/feature-gates/feature-gate-doc_notable_trait.rs Normal file
View File

@ -0,0 +1,4 @@
#[doc(notable_trait)] //~ ERROR: `#[doc(notable_trait)]` is experimental
trait SomeTrait {}
fn main() {}

12
src/test/ui/feature-gates/feature-gate-doc_notable_trait.stderr Normal file
View File

@ -0,0 +1,12 @@
error[E0658]: `#[doc(notable_trait)]` is experimental
--> $DIR/feature-gate-doc_notable_trait.rs:1:1
|
LL | #[doc(notable_trait)]
| ^^^^^^^^^^^^^^^^^^^^^
|
= note: see issue #45040 <https://github.com/rust-lang/rust/issues/45040> for more information
= help: add `#![feature(doc_notable_trait)]` to the crate attributes to enable
error: aborting due to previous error
For more information about this error, try `rustc --explain E0658`.

4
src/test/ui/feature-gates/feature-gate-doc_spotlight.rs
View File

@ -1,4 +0,0 @@
#[doc(spotlight)] //~ ERROR: `#[doc(spotlight)]` is experimental
trait SomeTrait {}
fn main() {}

12
src/test/ui/feature-gates/feature-gate-doc_spotlight.stderr
View File

@ -1,12 +0,0 @@
error[E0658]: `#[doc(spotlight)]` is experimental
--> $DIR/feature-gate-doc_spotlight.rs:1:1
|
LL | #[doc(spotlight)]
| ^^^^^^^^^^^^^^^^^
|
= note: see issue #45040 <https://github.com/rust-lang/rust/issues/45040> for more information
= help: add `#![feature(doc_spotlight)]` to the crate attributes to enable
error: aborting due to previous error
For more information about this error, try `rustc --explain E0658`.