API Docs: convert

[steveklabnik]

Part of #29329

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

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

• the module documentation is great, but has a lot of abbreviations, so the wording could be cleaned up a bit.
• AsMut should compare itself to AsRef, and should show a sample implementation.
• AsRef needs far better docs, as it is one of the most misunderstood traits in Rust. Specifically it should talk about its relationship with Borrow. It also needs an example implementation.
• From needs a lot of work; it should talk about its usage in ?, it should show an example implementation, and general improvement.
• Into is mostly fine, but "generic impls" should say "implementations" and it should be above examples.

[steveklabnik]

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

[maccoda]

I would be keen to give this one a go @steveklabnik I'm interested in understanding this section better.

[steveklabnik]

Awesome, @maccoda ! Let me know if I can help you help me in any way 😄

[maccoda]

Hey @steveklabnik ,
Just a couple of questions:

1. In the issue description for the Into trait you say to have the generic implementations above the examples,

and it should be above examples.

It turns out all of the traits have the examples above the generic implementations. Should I move the generic implementations above the examples for all of the traits?

2. In adding sample implementation do you like to make a generic example or use a common example from the std lib? I only ask because I have become familiar with AsRef through the usage within the fs package in creating paths and was thinking of using this as an example. What are your thoughts?

3. The AsRef relationship with Borrow is where I am having a bit of trouble explaining this concisely. Are we wanting to have a brief summarization of the section in the book and do we need to reciprocate or align with the documentation for the Borrow trait? I only ask as I feel to explain the difference I am describing the Borrow trait a bit and do not want to introduce a second differing description.

Thanks 😄

[steveklabnik]

Hey @maccoda !

Should I move the generic implementations above the examples for all of the traits?

Yes, that'd be great!

In adding sample implementation do you like to make a generic example or use a common example from the std lib?

Ideally, we'd have both: one extremely simple example for people to be able to copy/paste, and one more realistic example. Feel free to submit one or both 😄

The AsRef relationship with Borrow is where I am having a bit of trouble explaining this concisely.

yes it's tough!

Are we wanting to have a brief summarization of the section in the book and do we need to reciprocate or align with the documentation for the Borrow trait?

The second edition of the book does not have that chapter; synchronizing these API docs is the right way to go 👍

[maccoda]

OK great 😄 I will hopefully have something in today to start picking apart. 👍

[maccoda]

Hey @steveklabnik ,
I had a look at the RFC mentioned in the contribution guide and couldn't find anything on the guidelines for line length. I only ask as one of the Travis builds failed due to the line exceeding 100 chars, so was wondering what I should be aiming for.

Thanks again! 😄

[steveklabnik]

Standard library docs are wrapped to 80 characters. :)

…

On Sat, Apr 1, 2017 at 1:22 AM, Dylan Maccora ***@***.***> wrote: Hey @steveklabnik </~https://github.com/steveklabnik> , I had a look at the RFC </~https://github.com/rust-lang/rfcs/blob/master/text/1574-more-api-documentation-conventions.md#appendix-a-full-conventions-text> mentioned in the contribution guide and couldn't find anything on the guidelines for line length. I only ask as one of the Travis builds failed due to the line exceeding 100 chars, so was wondering what I should be aiming for. Thanks again! 😄 — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#29349 (comment)>, or mute the thread </~https://github.com/notifications/unsubscribe-auth/AABsiphLIB5c0gFq2Joe5J1f1_iLAzyQks5rrd8qgaJpZM4GV1Nw> .

[steveklabnik]

This is now done! 🎊