mikros/rust
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Rollup merge of #102661 - chrysn-pull-requests:rustdoc-effect-of-fundamental, r=notriddle

Browse Source 
rustdoc: Document effect of fundamental types

This was implemented in https://github.com/rust-lang/rust/pull/96565, but not documented. But it's a useful feature for everyone who implements own wrapper (especially wrappers-around-pointers) types, so that they can behave like pointers (and stdlib wrappers) do -- so here goes a mention in the unstable section of the rustdoc book.

(That is where I initially looked to find tricks for making my own wrapper types be transparent to documentation).
This commit is contained in:
Michael Howell 2022-10-08 18:15:00 -07:00 committed by GitHub
commit 825014e889
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 29 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
src/doc/rustdoc/src/unstable-features.md
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