Option and Result: Add references to documentation of as_ref and as_mut
This makes the documentation more consistent with that of `Pin::as_ref` which converts "from `&Pin<Pointer<T>>` to `Pin<&t>`".
This generally makes it clearer that the reference is going inside the option.
No old chestnuts in iter::repeat docs
The current language may be amusing, yet is just imprecise and most especially difficult to understand for someone who speaks English as a foreign language.
Stabilize Range*::contains.
Closes https://github.com/rust-lang/rust/issues/32311. There's also a bit of rustfmt on range.rs thrown in for good measure (I forgot to turn off format-on-save in VSCode).
A few improvements to comments in user-facing crates
Not too many this time, and all concern comments (almost all doc comments) in user-facing crates (libstd, libcore, liballoc).
r? @steveklabnik
The current language may be amusing, yet is just imprecise and most especially difficult to understand for someone who speaks English as a foreign language.
Simplify Iterator::{min, max}
This PR simplifies the `select_fold1` helper method used to implmement `Iterator::{min, min_by, min_by_key, max, max_by, max_by_key}` by removing the projection argument, which was only used by the implementations of `min_by_key` and `max_by_key`.
I also added tests to ensure that the stability as mentioned in the comments of `min` and `max` is preserved, and fixed the `iter::{bench_max, bench_max_by_key}` benchmarks which the compiler presumably was able to collapse into closed-form expressions. None of the benchmark results were impacted, I suspect their generated assembly didn't change.
Standardize `Range*` documentation
This updates the final example in the documentation for the types
`Range`, `RangeFrom`, `RangeFull`, `RangeInclusive`, `RangeTo`,
`RangeToInclusive`.
Use lifetime contravariance to elide more lifetimes in core+alloc+std
Sample:
```diff
- impl<'a, 'b, A: ?Sized, B: ?Sized> PartialEq<&'b mut B> for &'a mut A where A: PartialEq<B> {
+ impl<A: ?Sized, B: ?Sized> PartialEq<&mut B> for &mut A where A: PartialEq<B> {
#[inline]
- fn eq(&self, other: &&'b mut B) -> bool { PartialEq::eq(*self, *other) }
+ fn eq(&self, other: &&mut B) -> bool { PartialEq::eq(*self, *other) }
#[inline]
- fn ne(&self, other: &&'b mut B) -> bool { PartialEq::ne(*self, *other) }
+ fn ne(&self, other: &&mut B) -> bool { PartialEq::ne(*self, *other) }
}
```
[I didn't know this worked](https://internals.rust-lang.org/t/why-can-you-use-different-unconstrained-lifetimes-to-implement-traits/9544/2?u=scottmcm) until recently, but since defining methods contravariantly in their lifetimes this way has worked back to Rust 1.0, we might as well take advantage of combining it with IHLE.
Fix documentation of from_ne_bytes and from_le_bytes
Copypasta mistake, the documentation of `from_ne_bytes` and `from_le_bytes` used the big-endian variant in the example snippets.
Expand docs for `TryFrom` and `TryInto`.
The examples are still lacking for now, both for module docs and for methods/impl's. Will be adding those in further pushes.
Should hopefully resolve the doc concern in #33417 when finished?
Add as_slice() to slice::IterMut and vec::Drain
In bluss/indexmap#88, we found that there was no easy way to implement
`Debug` for our `IterMut` and `Drain` iterators. Those are built on
`slice::IterMut` and `vec::Drain`, which implement `Debug` themselves,
but have no other way to access their data. With a new `as_slice()`
method, we can read the data and customize its presentation.
MaybeUninit: add read_initialized, add examples
This adds a new `read_initialized` method, similar to suggestions by @Amanieu and @shepmaster. I also added examples to this and other methods.
overhaul unused doc comments lint
This PR contains a number of improvements to the `unused_doc_comments` lint.
- Extends the span to cover the entire comment when using sugared doc comments.
- Triggers the lint for all unused doc comments on a node, instead of just the first one.
- Triggers the lint on macro expansions, and provides a help note explaining that doc comments must be expanded by the macro.
- Adds a label pointing at the node that cannot be documented.
Furthermore, this PR fixes any instances in rustc where a macro expansion was erroneously documented.
