rust-lang/rust

API Docs: std::ops

steveklabnik opened this issue · 10 comments

steveklabnik commented

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.
bluss commented

Sub issues:

  • Carrier doc says it is implemented for Option, but it is not, so docs are not in sync with code.
  • Carrier doc should say that it is not intended to be used directly #37751 (comment)
steveklabnik commented

I am happy to mentor anyone who wants to tackle this issue.

theotherphil commented

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

steveklabnik commented

@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 commented

Great, thanks.

terrynsun commented

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

theotherphil commented

@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 commented

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

mandeep commented

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

chordowl commented

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