[rustc.git] / src / doc / unstable-book / src / language-features / doc-spotlight.md

# `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
Commit	Line	Data
3dfed10e XL	1	# `doc_spotlight`
	2
	3	The tracking issue for this feature is: [#45040]
	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
6a06907d XL	8	a type that implements that trait. For example, this attribute is applied to the `Iterator`,
6a06907d XL	9	`io::Read`, `io::Write`, and `Future` traits in the standard library.
3dfed10e XL	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 [#45039].
	28
	29	[#45040]: https://github.com/rust-lang/rust/issues/45040
	30	[#45039]: https://github.com/rust-lang/rust/pull/45039