Improve std::ops docs
Fixes#29365. (This fixes all but one point from @steveklabnik's list, but that point was referring to examples of implementing range traits, but there are no range traits in std::ops.)
The main changes are quite a bit of copyediting, adding more "real" examples for some of the traits, incorporating some guidance from the API docs, more linking (cross-docs and to the book & reference), cleaning up examples, moving things around, and so on. Refer to the commit messages for more details.
Note: I decided to link to the second edition of the book since I think it's more appropriate now for the sections I linked, if this is not okay, please say so!
* fixed link typos and copy-paster errors
* rewrote Fn* explanations
* `RHS = Self` -> `RHS` is `Self` (added that to all applicable places as
well)
* fixed up some links
* s/MutDeref/DerefMut
* removed remaining superfluous `fn main()`s
* fixed some minor phrasings and factual errors and inaccuracies
std::ops docs: Fix phrasing and factual errors/inaccuracies
Part of #29365.
* Added paragraph adapted from API guidelines that operator implementations
should be unsurprising
* Modified Point example to be more clear when just reading it
Part of #29365.
* Strenghtened summary/explanation split, making phrasings more parallel
* Added links throughout
* Fixed some example formatting & removed extraneous `fn main()`s (or hid
then when needed because of `#![features]`.
* Emphasized note on `RangeFrom`'s `Iterator` implementation
* Added summary sentences to (unstable) `contains` methods
Part of #29365.
* Moved explanations out of Examples section and expanded on them.
* Made the super-/subtrait relationships more explicit.
* Added links to the other traits, TRPL and the nomicon where appropriate
* Changed method summaries to be in 3rd person singular
* General copyediting
Part of #29365.
* Shortened summary sentences, removing "stuttering"
* Small copyediting
* Changed method summary sentences to be in 3rd person singular
* Removed extraneous explicit `fn main()` in example for `IndexMut`
Part of #29365.
* Removed "stuttering" in summary sentence.
* Copy-edited the explanaition sections
* Added sub-headings in Examples section to aid linking
* Actually implement `Drop` in the `PrintOnDrop` exampl
* Add link to Drop chapter in TRPL
* Changed `drop` summary sentence to be in 3rd person singular
* Added missing link to `panic!`
Part of #29365.
* Expanded the explanaition sections, adapting some parts from the book,
the reference, as well as the API guidelines. As such, the docs now
explicitly state that `Deref` and `DerefMut` should only be implemented
for smart pointers and that they should not fail. Additionally, there
is now a short primer on `Deref` coercion.
* Added links to `DerefMut` from `Deref` and vice versa
* Added links to relevant reference sections
* Removed "stuttering" in summary sentences
* Changed summary sentences of `Deref::deref` and `Deref::deref_mut` to
be in 3rd person singular
* Removed explicit uses of `fn main()` in the examples
Part of #29365.
* Added "real" examples for `BitOrAssign`, `BitXorAssign`, `ShlAssign`,
and `ShrAssign`
* Rewrote method summary senteces to be in 3rd person singular
* Rephrased example introductions to be less redundant ("in this example"
etc.) and to not use "trivial"
* Removed superfluous explicit `fn main()`s in examples
* Added some missing periods
Part of #29365.
* Replaced examples for Mul-/Div-/RemAssign with more illustrative ones
* Made summary senteces for the trait methods use third person singular
* Moved some explanations from Examples section to main explanation
* Switched around argument order for the vector-scalar multiplication
example such that the vector is on the left side (as it would be expected
if one were to switch from `*` to `*=`)
* Replaced mostly redundant example introductions with headings in traits
with more than one example (where it made sense)
* Cleaned up some examples to derive `PartialEq` instead of implementing it
manually when that wasn't needed
* Removed explicit `fn main()`s in examples where they weren't necessary
* Rephrased some things
* Added some missing periods
* Fixed some formatting/punctuation in examples
Replaced by adding extra imports, adding hidden code (`# ...`), modifying
examples to be runnable (sorry Homura), specifying non-Rust code, and
converting to should_panic, no_run, or compile_fail.
Remaining "```ignore"s received an explanation why they are being ignored.
