Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Auto merge of #45039 - QuietMisdreavus:doc-spotlight, r=GuillaumeGome…
…z,QuietMisdreavus show in docs whether the return type of a function impls Iterator/Read/Write Closes #25928 This PR makes it so that when rustdoc documents a function, it checks the return type to see whether it implements a handful of specific traits. If so, it will print the impl and any associated types. Rather than doing this via a whitelist within rustdoc, i chose to do this by a new `#[doc]` attribute parameter, so things like `Future` could tap into this if desired. ### Known shortcomings ~~The printing of impls currently uses the `where` class over the whole thing to shrink the font size relative to the function definition itself. Naturally, when the impl has a where clause of its own, it gets shrunken even further:~~ (This is no longer a problem because the design changed and rendered this concern moot.) The lookup currently just looks at the top-level type, not looking inside things like Result or Option, which renders the spotlights on Read/Write a little less useful: <details><summary>`File::{open, create}` don't have spotlight info (pic of old design)</summary> ![image](https://user-images.githubusercontent.com/5217170/31209495-e59d027e-a950-11e7-9998-ceefceb71c07.png) </details> All three of the initially spotlighted traits are generically implemented on `&mut` references. Rustdoc currently treats a `&mut T` reference-to-a-generic as an impl on the reference primitive itself. `&mut Self` counts as a generic in the eyes of rustdoc. All this combines to create this lovely scene on `Iterator::by_ref`: <details><summary>`Iterator::by_ref` spotlights Iterator, Read, and Write (pic of old design)</summary> ![image](https://user-images.githubusercontent.com/5217170/31209554-50b271ca-a951-11e7-928b-4f83416c8681.png) </details>
- Loading branch information
Showing
13 changed files
with
345 additions
and
14 deletions.
There are no files selected for viewing
30 changes: 30 additions & 0 deletions
30
src/doc/unstable-book/src/language-features/doc-spotlight.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,30 @@ | ||
# `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. 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 [#45039]. | ||
|
||
[#45040]: https://github.com/rust-lang/rust/issues/45040 | ||
[#45039]: https://github.com/rust-lang/rust/pull/45039 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.