RFC 2008 non-exhaustive enums/structs: Rustdoc
Part of #44109. Not sure how those who maintain rustdoc primarily would prefer this addition look or where it should be placed, happy to make any changes required.
r? @QuietMisdreavus (not sure if this is the right person, just guessing)
Fix collapse toggle insertions on impl with docs
Just went through this one randomly... When an impl has docs, the collapse toggle isn't generated. This fixes it.
r? @QuietMisdreavus
Remember state of top-level collapse toggle widget
This change allows the big top-right expand/collapse toggle to remember its setting across navigation or page reloads. Prior to this change, there was this annoyance:
- browse to some docs
- Click the minus button to collapse them
- browse to other docs (or reload the page)
- Everything is expanded again
The solution is based on storing a simple boolean flag in localStorage. I think it's a good improvement, but it does introduce the following potentially surprising behavior:
- browse to some docs
- click the minus button to collapse them
- click to expand a particular item (not the main top-right big one)
- reload the page, everything is collapsed
Paired with @debugsteven on this.
rustdoc: Foldable impl blocks
Addresses #40363, #45720, #24483, #23986 and so on
* Expands and refactors collapseDocs and toggleAllDocs
* Adds [-] toggle to all impls (including inherent impl)
* Makes it hiding though main css file, not though element inline style
May need to be addressed:
* "[-]" and anchor link copier are overlaid a bit
* Inherent methods are also hidden by the global [-] toggle.
* Auto-collapsing "Iterator" and so on by default is not implemented yet
* Tested only shallowly and only in Chromiuim
* No tests. Are there tests for css/js part here?
* The new implementation may be a bit slower.
What next steps are need to be done before the integration?
A new section is added to both both struct and trait doc pages.
On struct/enum pages, a new 'Auto Trait Implementations' section displays any
synthetic implementations for auto traits. Currently, this is only done
for Send and Sync.
On trait pages, a new 'Auto Implementors' section displays all types
which automatically implement the trait. Effectively, this is a list of
all public types in the standard library.
Synthesized impls for a particular auto trait ('synthetic impls') take
into account generic bounds. For example, a type 'struct Foo<T>(T)' will
have 'impl<T> Send for Foo<T> where T: Send' generated for it.
Manual implementations of auto traits are also taken into account. If we have
the following types:
'struct Foo<T>(T)'
'struct Wrapper<T>(Foo<T>)'
'unsafe impl<T> Send for Wrapper<T>' // pretend that Wrapper<T> makes
this sound somehow
Then Wrapper will have the following impl generated:
'impl<T> Send for Wrapper<T>'
reflecting the fact that 'T: Send' need not hold for 'Wrapper<T>: Send'
to hold
Lifetimes, HRTBS, and projections (e.g. '<T as Iterator>::Item') are
taken into account by synthetic impls
However, if a type can *never* implement a particular auto trait
(e.g. 'struct MyStruct<T>(*const T)'), then a negative impl will be
generated (in this case, 'impl<T> !Send for MyStruct<T>')
All of this means that a user should be able to copy-paste a synthetic
impl into their code, without any observable changes in behavior
(assuming the rest of the program remains unchanged).
Addresses #40363, #45720, #24483, #23986 and so on
* Expands and refactors collapseDocs and toggleAllDocs
* Adds [-] toggle to all impls (including inherent impl)
* Makes it hiding though main css file, not though element style
May need to be addressed:
* "[-]" and anchor link copier are overlaid a bit
* Inherent methods are also hidden by the global [-] toggle.
* Auto-collapsing "Iterator" and so on by default is not implemented yet
* Tested only shallowly and only in Chromiuim
* No tests. Are there tests for css/js part here?
* The new implementation may be a bit slower.
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>
</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>
</details>
