API Docs: std::ops #29365

steveklabnik · 2015-10-26T17:29:48Z

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".

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

…=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

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

…=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

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

…=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

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

…=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

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

…=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

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

…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

Add missing urls for ops module Part of rust-lang#29365. r? @steveklabnik

theotherphil · 2017-03-24T19:44:20Z

I'd like to give this a go. Is there a getting started guide to contributing docs changes?

steveklabnik · 2017-03-24T19:59:41Z

@theotherphil great!

Is there a getting started guide to contributing docs changes?

We have https://github.com/rust-lang/rust/blob/master/CONTRIBUTING.md#writing-documentation, but I'd like to add more :) For example, https://github.com/rust-lang/rfcs/blob/master/text/1574-more-api-documentation-conventions.md is a big list of conventions, though you don't need to really know them well to submit PRs; we'll make sure it follows them in the review.

As far as this specific stuff goes, https://github.com/rust-lang/rust/blob/master/src/libcore/ops.rs is the file you'll want to edit; everything here should be in there.

I'm happy to elaborate with more detail, but that should maybe get you started? 😄

theotherphil · 2017-03-24T20:13:02Z

Great, thanks.

@steveklabnik

Don't stutter in operator trait descriptions Fixes first item on rust-lang#29365. r? @steveklabnik

@steveklabnik

Don't stutter in operator trait descriptions Fixes first item on rust-lang#29365. r? @steveklabnik

terrynsun · 2017-03-28T23:20:24Z

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

theotherphil · 2017-03-29T06:44:40Z

@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 · 2017-03-30T00:10:17Z

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

mandeep · 2017-04-17T02:30:39Z

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

…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.

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.

chordowl · 2017-08-06T20:25:08Z

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.).

@steveklabnik

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!

steveklabnik added the A-docs label Oct 26, 2015

steveklabnik mentioned this issue Oct 26, 2015

The Standard Library Documentation Checklist #29329

Closed

51 tasks

matthew-piziak mentioned this issue Aug 16, 2016

replace Add example with something more evocative of addition #35709

Merged

matthew-piziak mentioned this issue Aug 16, 2016

note that calling drop() explicitly is a compiler error #35710

Merged

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…

b0b57cf

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

sophiajt pushed a commit to sophiajt/rust that referenced this issue Aug 19, 2016

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

bb03ef1

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

sophiajt pushed a commit to sophiajt/rust that referenced this issue Aug 19, 2016

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

f60a669

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

sophiajt pushed a commit to sophiajt/rust that referenced this issue Aug 20, 2016

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

7fc927f

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

sophiajt pushed a commit to sophiajt/rust that referenced this issue Aug 20, 2016

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

ba8611e

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

matthew-piziak mentioned this issue Aug 21, 2016

more evocative examples for Sub and SubAssign #35876

Merged

GuillaumeGomez mentioned this issue Sep 28, 2016

Add missing urls for ops module #36810

Merged

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

Rollup merge of rust-lang#36810 - GuillaumeGomez:ops_doc, r=steveklabnik

fb880df

Add missing urls for ops module Part of rust-lang#29365. r? @steveklabnik

steveklabnik added the E-medium Call for participation: Medium difficulty. Experience needed to fix: Intermediate. label Mar 24, 2017

theotherphil added a commit to theotherphil/rust that referenced this issue Mar 25, 2017

Don't stutter in operator descriptions rust-lang#29365

8b92255

theotherphil mentioned this issue Mar 25, 2017

Don't stutter in operator trait descriptions #40818

Merged

frewsxcv added a commit to frewsxcv/rust that referenced this issue Mar 26, 2017

Rollup merge of rust-lang#40818 - theotherphil:master, r=steveklabnik

24b40a6

Don't stutter in operator trait descriptions Fixes first item on rust-lang#29365. r? @steveklabnik

alexcrichton added a commit to alexcrichton/rust that referenced this issue Mar 27, 2017

Rollup merge of rust-lang#40818 - theotherphil:master, r=steveklabnik

bae772b

Don't stutter in operator trait descriptions Fixes first item on rust-lang#29365. r? @steveklabnik

mandeep mentioned this issue Apr 28, 2017

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

Merged

mandeep mentioned this issue Jul 22, 2017

Add generic example of std::ops::Sub in doc comments #43413

Merged

Mark-Simulacrum added the C-tracking-issue Category: A tracking issue for an RFC or an unstable feature. label Jul 24, 2017

chordowl mentioned this issue Aug 7, 2017

Improve std::ops docs #43724

Merged

bors closed this as completed in #43724 Aug 12, 2017

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

API Docs: std::ops #29365

API Docs: std::ops #29365

steveklabnik commented Oct 26, 2015 •

edited

Loading

theotherphil commented Mar 24, 2017 •

edited

Loading

steveklabnik commented Mar 24, 2017

theotherphil commented Mar 24, 2017

terrynsun commented Mar 28, 2017

theotherphil commented Mar 29, 2017

terrynsun commented Mar 30, 2017

mandeep commented Apr 17, 2017

chordowl commented Aug 6, 2017

API Docs: std::ops #29365

API Docs: std::ops #29365

Comments

steveklabnik commented Oct 26, 2015 • edited Loading

theotherphil commented Mar 24, 2017 • edited Loading

steveklabnik commented Mar 24, 2017

theotherphil commented Mar 24, 2017

terrynsun commented Mar 28, 2017

theotherphil commented Mar 29, 2017

terrynsun commented Mar 30, 2017

mandeep commented Apr 17, 2017

chordowl commented Aug 6, 2017

steveklabnik commented Oct 26, 2015 •

edited

Loading

theotherphil commented Mar 24, 2017 •

edited

Loading