rustdoc: Document effect of fundamental types

This commit is contained in:
chrysn 2022-10-04 16:55:40 +02:00
parent ead49f0beb
commit 31bc385fa1

View file

@ -197,6 +197,35 @@ To do so, the `#[doc(keyword = "...")]` attribute is used. Example:
mod empty_mod {}
```
## Effects of other nightly features
These nightly-only features are not primarily related to Rustdoc,
but have convenient effects on the documentation produced.
### `fundamental` types
Annotating a type with `#[fundamental]` primarily influences coherence rules about generic types,
i.e., they alter whether other crates can provide implementations for that type.
The unstable book [links to further information][unstable-fundamental].
[unstable-fundamental]: https://doc.rust-lang.org/unstable-book/language-features/fundamental.html
For documentation, this has an additional side effect:
If a method is implemented on `F<T>` (or `F<&T>`),
where `F` is a fundamental type,
then the method is not only documented at the page about `F`,
but also on the page about `T`.
In a sense, it makes the type transparent to Rustdoc.
This is especially convenient for types that work as annotated pointers,
such as `Pin<&mut T>`,
as it ensures that methods only implemented through those annotated pointers
can still be found with the type they act on.
If the `fundamental` feature's effect on coherence is not intended,
such a type can be marked as fundamental only for purposes of documentation
by introducing a custom feature and
limiting the use of `fundamental` to when documentation is built.
## Unstable command-line arguments
These features are enabled by passing a command-line flag to Rustdoc, but the flags in question are