New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

API Docs: std::ops #29365

Closed
steveklabnik opened this Issue Oct 26, 2015 · 10 comments

Comments

Projects
None yet
7 participants
@steveklabnik
Member

steveklabnik commented Oct 26, 2015

Part of #29329

http://doc.rust-lang.org/std/ops/

Here's what needs to be done to close out this issue:

  • almost all of the traits suffer from "stuttering", that is, their summary lines should drop "the X trait" and say "the X operator", with the symbol. #40818
  • Range needs a better summary/explanation distinction.
  • RangeFrom has the same issue.
  • RangeFull same
  • RangeTo same
  • All of these range traits could use examples of implementing them to let people pass ranges directly, with examples.
  • Deref is a very important trait with little documentation.
  • DerefMut should link to Deref, and vice versa.
  • Drop is very important yet has little documentation.
  • Fn has a bad summary and a lot of its explanation is inside of the example.
  • FnMut same
  • FnOnce same
  • Some traits only have "prints when called" examples, while others have amazing, real examples. Improving these would be nice but isn't required to close this ticket.

@steveklabnik steveklabnik added the A-docs label Oct 26, 2015

matthew-piziak added a commit to matthew-piziak/rust that referenced this issue Aug 16, 2016

replace Add example with something more evocative of addition
Currently most of the operator traits use trivial implementation
examples that only perform side effects. Honestly, that might not be too
bad for the sake of documentation; but anyway, here's a proposal to move
a slightly modified version of the module-level point-addition example
into the `Add` documentation, since it's more evocative of addition
semantics.

Part of rust-lang#29365

matthew-piziak added a commit to matthew-piziak/rust that referenced this issue Aug 16, 2016

matthew-piziak added a commit to matthew-piziak/rust that referenced this issue Aug 17, 2016

note that calling drop() explicitly is a compiler error
Part of rust-lang#29365

explain that std::mem::drop in prelude will invoke Drop

change "prelude" -> "the prelude"; change links to reference-style

move link references to links' section

matthew-piziak added a commit to matthew-piziak/rust that referenced this issue Aug 17, 2016

replace Add example with something more evocative of addition
Currently most of the operator traits use trivial implementation
examples that only perform side effects. Honestly, that might not be too
bad for the sake of documentation; but anyway, here's a proposal to move
a slightly modified version of the module-level point-addition example
into the `Add` documentation, since it's more evocative of addition
semantics.

Part of rust-lang#29365

wrap identifiers in backticks

minor rephrasing

matthew-piziak added a commit to matthew-piziak/rust that referenced this issue Aug 18, 2016

replace Add example with something more evocative of addition
Currently most of the operator traits use trivial implementation
examples that only perform side effects. Honestly, that might not be too
bad for the sake of documentation; but anyway, here's a proposal to move
a slightly modified version of the module-level point-addition example
into the `Add` documentation, since it's more evocative of addition
semantics.

Part of rust-lang#29365

wrap identifiers in backticks

minor rephrasing

fix module-level documentation to be more truthful

This branch changes the example for `Add` to no longer be a "minimum implementation that prints something to the screen".

matthew-piziak added a commit to matthew-piziak/rust that referenced this issue Aug 18, 2016

note that calling drop() explicitly is a compiler error
Part of rust-lang#29365

explain that std::mem::drop in prelude will invoke Drop

change "prelude" -> "the prelude"; change links to reference-style

move link references to links' section

matthew-piziak added a commit to matthew-piziak/rust that referenced this issue Aug 18, 2016

note that calling drop() explicitly is a compiler error
Part of rust-lang#29365

explain that std::mem::drop in prelude will invoke Drop

change "prelude" -> "the prelude"; change links to reference-style

move link references to links' section

steveklabnik added a commit to steveklabnik/rust that referenced this issue Aug 18, 2016

Rollup merge of rust-lang#35709 - matthew-piziak:add-trait-example, r…
…=GuillaumeGomez

replace `Add` example with something more evocative of addition

Currently most of the operator traits use trivial implementation
examples that only perform side effects. Honestly, that might not be too
bad for the sake of documentation; but anyway, here's a proposal to move
a slightly modified version of the module-level point-addition example
into the `Add` documentation, since it's more evocative of addition
semantics.

Part of rust-lang#29365

steveklabnik added a commit to steveklabnik/rust that referenced this issue Aug 18, 2016

Rollup merge of rust-lang#35710 - matthew-piziak:explicit-drop, r=ste…
…veklabnik

note that calling drop() explicitly is a compiler error

Part of rust-lang#29365

jonathandturner added a commit to jonathandturner/rust that referenced this issue Aug 19, 2016

Rollup merge of rust-lang#35709 - matthew-piziak:add-trait-example, r…
…=GuillaumeGomez

replace `Add` example with something more evocative of addition

Currently most of the operator traits use trivial implementation
examples that only perform side effects. Honestly, that might not be too
bad for the sake of documentation; but anyway, here's a proposal to move
a slightly modified version of the module-level point-addition example
into the `Add` documentation, since it's more evocative of addition
semantics.

Part of rust-lang#29365

jonathandturner added a commit to jonathandturner/rust that referenced this issue Aug 19, 2016

Rollup merge of rust-lang#35710 - matthew-piziak:explicit-drop, r=ste…
…veklabnik

note that calling drop() explicitly is a compiler error

Part of rust-lang#29365

jonathandturner added a commit to jonathandturner/rust that referenced this issue Aug 19, 2016

Rollup merge of rust-lang#35709 - matthew-piziak:add-trait-example, r…
…=GuillaumeGomez

replace `Add` example with something more evocative of addition

Currently most of the operator traits use trivial implementation
examples that only perform side effects. Honestly, that might not be too
bad for the sake of documentation; but anyway, here's a proposal to move
a slightly modified version of the module-level point-addition example
into the `Add` documentation, since it's more evocative of addition
semantics.

Part of rust-lang#29365

jonathandturner added a commit to jonathandturner/rust that referenced this issue Aug 19, 2016

Rollup merge of rust-lang#35710 - matthew-piziak:explicit-drop, r=ste…
…veklabnik

note that calling drop() explicitly is a compiler error

Part of rust-lang#29365

jonathandturner added a commit to jonathandturner/rust that referenced this issue Aug 20, 2016

Rollup merge of rust-lang#35709 - matthew-piziak:add-trait-example, r…
…=GuillaumeGomez

replace `Add` example with something more evocative of addition

Currently most of the operator traits use trivial implementation
examples that only perform side effects. Honestly, that might not be too
bad for the sake of documentation; but anyway, here's a proposal to move
a slightly modified version of the module-level point-addition example
into the `Add` documentation, since it's more evocative of addition
semantics.

Part of rust-lang#29365

jonathandturner added a commit to jonathandturner/rust that referenced this issue Aug 20, 2016

Rollup merge of rust-lang#35710 - matthew-piziak:explicit-drop, r=ste…
…veklabnik

note that calling drop() explicitly is a compiler error

Part of rust-lang#29365

jonathandturner added a commit to jonathandturner/rust that referenced this issue Aug 20, 2016

Rollup merge of rust-lang#35710 - matthew-piziak:explicit-drop, r=ste…
…veklabnik

note that calling drop() explicitly is a compiler error

Part of rust-lang#29365

jonathandturner added a commit to jonathandturner/rust that referenced this issue Aug 20, 2016

Rollup merge of rust-lang#35709 - matthew-piziak:add-trait-example, r…
…=GuillaumeGomez

replace `Add` example with something more evocative of addition

Currently most of the operator traits use trivial implementation
examples that only perform side effects. Honestly, that might not be too
bad for the sake of documentation; but anyway, here's a proposal to move
a slightly modified version of the module-level point-addition example
into the `Add` documentation, since it's more evocative of addition
semantics.

Part of rust-lang#29365

matthew-piziak added a commit to matthew-piziak/rust that referenced this issue Aug 21, 2016

more evocative examples for `Sub` and `SubAssign`
These examples are exactly analogous to those in PRs rust-lang#35709 and rust-lang#35806.
I'll probably remove the `fn main` wrappers for `Add` and `Sub` once
this is merged in.

Part of rust-lang#29365.

r? @steveklabnik

matthew-piziak added a commit to matthew-piziak/rust that referenced this issue Aug 21, 2016

more evocative examples for `Sub` and `SubAssign`
These examples are exactly analogous to those in PRs rust-lang#35709 and rust-lang#35806. I'll probably remove the `fn main` wrappers for `Add` and `Sub` once this is merged in.

Part of rust-lang#29365.

r? @steveklabnik

matthew-piziak added a commit to matthew-piziak/rust that referenced this issue Aug 22, 2016

more evocative examples for `Sub` and `SubAssign`
These examples are exactly analogous to those in PRs rust-lang#35709 and rust-lang#35806. I'll probably remove the `fn main` wrappers for `Add` and `Sub` once this is merged in.

Part of rust-lang#29365.

r? @steveklabnik

matthew-piziak added a commit to matthew-piziak/rust that referenced this issue Aug 22, 2016

more evocative examples for `Sub` and `SubAssign`
These examples are exactly analogous to those in PRs rust-lang#35709 and rust-lang#35806. I'll probably remove the `fn main` wrappers for `Add` and `Sub` once this is merged in.

Part of rust-lang#29365.

r? @steveklabnik

jonathandturner added a commit to jonathandturner/rust that referenced this issue Aug 24, 2016

Rollup merge of rust-lang#35876 - matthew-piziak:sub-examples, r=Guil…
…laumeGomez

more evocative examples for `Sub` and `SubAssign`

These examples are exactly analogous to those in PRs rust-lang#35709 and rust-lang#35806. I'll probably remove the `fn main` wrappers for `Add` and `Sub` once this is merged in.

Part of rust-lang#29365.

r? @steveklabnik

steveklabnik added a commit to steveklabnik/rust that referenced this issue Sep 30, 2016

steveklabnik added a commit to steveklabnik/rust that referenced this issue Sep 30, 2016

@terrynsun

This comment has been minimized.

Contributor

terrynsun commented Mar 28, 2017

I'd like to help on this too. @theotherphil, which of the sub-issues are you working on/ want to work on?

@theotherphil

This comment has been minimized.

Contributor

theotherphil commented Mar 29, 2017

@terrynsun: I've done the first issue and have started to think a little about the next five (i.e. all the RangeX) issues. I've not looked at the others - do you want to do those? (Or split the work any other way?)

@terrynsun

This comment has been minimized.

Contributor

terrynsun commented Mar 30, 2017

I can take a shot at Deref/DerefMut/Drop.

@mandeep

This comment has been minimized.

Contributor

mandeep commented Apr 17, 2017

I'll be working on the last item in the list. Specifically, adding examples of implementing traits with generics.

Mark-Simulacrum added a commit to Mark-Simulacrum/rust that referenced this issue May 14, 2017

Rollup merge of rust-lang#41612 - mandeep:add-ops-generics, r=Guillau…
…meGomez,frewsxcv

Added generic example of std::ops::Add in doc comments

We discussed on IRC how the std::ops examples were potentially missing examples using generics. This PR adds an example to std::ops::Add that shows the use of a generic type T. I'm not sure this is ready for merge as I think the two examples now make the documentation a bit verbose, but I think it's a good starting point. I'd love to hear others thoughts on this. This is in relation to the last item in issue rust-lang#29365.

bors added a commit that referenced this issue Jul 24, 2017

Auto merge of #43413 - mandeep:ops-generics, r=alexcrichton
Add generic example of std::ops::Sub in doc comments

This PR adds an example of using generics with std::ops::Sub and is a follow up of PR #41612 and is related to issue #29365. I also wanted to add examples to Mul and Div, but I think these two traits are already loaded with examples.
@lukaramu

This comment has been minimized.

Contributor

lukaramu commented Aug 6, 2017

I'm working on getting as much of this done as I can in the next few days; I've already noticed quite a few examples implement PartialEq manually when they don't have to (distracting from what is supposed to be shown). Additionally, I'll try to incorporate some of the API guidelines into the docs (e.g. that implementations should be unsurprising, that Deref/DerefMut should only be implemented for smart pointers, etc.).

lukaramu added a commit to lukaramu/rust that referenced this issue Aug 7, 2017

Revise documentation in core::ops::arith
Part of rust-lang#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

lukaramu added a commit to lukaramu/rust that referenced this issue Aug 7, 2017

Revise documentation in core::ops::bit
Part of rust-lang#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

lukaramu added a commit to lukaramu/rust that referenced this issue Aug 7, 2017

Expand docs on `Deref` and `DerefMut`
Part of rust-lang#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

lukaramu added a commit to lukaramu/rust that referenced this issue Aug 7, 2017

Revise `Drop` docs
Part of rust-lang#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!`

lukaramu added a commit to lukaramu/rust that referenced this issue Aug 7, 2017

Revise `Index` and `IndexMut` docs.
Part of rust-lang#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`

lukaramu added a commit to lukaramu/rust that referenced this issue Aug 7, 2017

Revise `Fn`/`FnMut`/`FnOnce` documentation
Part of rust-lang#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

lukaramu added a commit to lukaramu/rust that referenced this issue Aug 7, 2017

Revised core::ops::range::* docs
Part of rust-lang#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

lukaramu added a commit to lukaramu/rust that referenced this issue Aug 7, 2017

Added to core::ops module docs
Part of rust-lang#29365.
* Added paragraph adapted from API guidelines that operator implementations
  should be unsurprising
* Modified Point example to be more clear when just reading it

lukaramu added a commit to lukaramu/rust that referenced this issue Aug 7, 2017

Added to core::ops module docs
Part of rust-lang#29365.
* Added paragraph adapted from API guidelines that operator implementations
  should be unsurprising
* Modified Point example to be more clear when just reading it

bors added a commit that referenced this issue Aug 12, 2017

Auto merge of #43724 - lukaramu:std-ops-docs, r=QuietMisdreavus
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!

@bors bors closed this in #43724 Aug 12, 2017

bjorn3 added a commit to bjorn3/rust that referenced this issue Sep 10, 2017

Revise documentation in core::ops::arith
Part of rust-lang#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

bjorn3 added a commit to bjorn3/rust that referenced this issue Sep 10, 2017

Revise documentation in core::ops::bit
Part of rust-lang#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

bjorn3 added a commit to bjorn3/rust that referenced this issue Sep 10, 2017

Expand docs on `Deref` and `DerefMut`
Part of rust-lang#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

bjorn3 added a commit to bjorn3/rust that referenced this issue Sep 10, 2017

Revise `Drop` docs
Part of rust-lang#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!`

bjorn3 added a commit to bjorn3/rust that referenced this issue Sep 10, 2017

Revise `Index` and `IndexMut` docs.
Part of rust-lang#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`

bjorn3 added a commit to bjorn3/rust that referenced this issue Sep 10, 2017

Revise `Fn`/`FnMut`/`FnOnce` documentation
Part of rust-lang#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

bjorn3 added a commit to bjorn3/rust that referenced this issue Sep 10, 2017

Revised core::ops::range::* docs
Part of rust-lang#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

bjorn3 added a commit to bjorn3/rust that referenced this issue Sep 10, 2017

Added to core::ops module docs
Part of rust-lang#29365.
* Added paragraph adapted from API guidelines that operator implementations
  should be unsurprising
* Modified Point example to be more clear when just reading it
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment