Improve the documentation for std::convert (From, Into, AsRef and AsMut) #59330

DevQps · 2019-03-20T22:25:37Z

Description

In this PR I updated the documentation of From, Into, AsRef and AsMut, as well as the general std::convert module documentation. The discussion in #59163 provided information that was not yet present in the docs, or was not expressed clearly enough. I tried to clarify the examples that were already present in the docs as well as add more information about considered best-practices that came out of the discussion in #59163

@steveklabnik I hope I didn't change too much. This is an initial version! I will scan through everything tomorrow as well again to see if I made any typo's or errors, and maybe make some small changes here and there.

All suggestions are welcome!

closes #59163

rust-highfive · 2019-03-20T22:25:40Z

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @shepmaster (or someone else) soon.

If any changes to this PR are deemed necessary, please add them as extra commits. This ensures that the reviewer can see what has changed since they last reviewed the code. Due to the way GitHub handles out-of-date commits, this should also make it reasonably obvious what issues have or haven't been addressed. Large or tricky changes may require several passes of review and changes.

Please see the contribution instructions for more information.

rust-highfive · 2019-03-20T22:42:45Z

The job x86_64-gnu-llvm-6.0 of your PR failed on Travis (raw log). Through arcane magic we have determined that the following fragments from the build log may contain information about the problem.

Click to expand the log.

travis_time:end:014fda7c:start=1553120794077718353,finish=1553120879772457804,duration=85694739451
$ git checkout -qf FETCH_HEAD
travis_fold:end:git.checkout

Encrypted environment variables have been removed for security reasons.
See https://docs.travis-ci.com/user/pull-requests/#pull-requests-and-security-restrictions
$ export SCCACHE_BUCKET=rust-lang-ci-sccache2
$ export SCCACHE_REGION=us-west-1
$ export GCP_CACHE_BUCKET=rust-lang-ci-cache
Setting environment variables from .travis.yml
---

[00:03:16] travis_fold:start:tidy
travis_time:start:tidy
tidy check
[00:03:16] tidy error: /checkout/src/libcore/convert.rs:9: line longer than 100 chars
[00:03:16] tidy error: /checkout/src/libcore/convert.rs:10: line longer than 100 chars
[00:03:16] tidy error: /checkout/src/libcore/convert.rs:199: line longer than 100 chars
[00:03:16] tidy error: /checkout/src/libcore/convert.rs:200: line longer than 100 chars
[00:03:16] tidy error: /checkout/src/libcore/convert.rs:201: line longer than 100 chars
[00:03:16] tidy error: /checkout/src/libcore/convert.rs:212: line longer than 100 chars
[00:03:16] tidy error: /checkout/src/libcore/convert.rs:236: line longer than 100 chars
[00:03:16] tidy error: /checkout/src/libcore/convert.rs:237: line longer than 100 chars
[00:03:16] tidy error: /checkout/src/libcore/convert.rs:277: line longer than 100 chars
[00:03:16] tidy error: /checkout/src/libcore/convert.rs:278: line longer than 100 chars
[00:03:16] tidy error: /checkout/src/libcore/convert.rs:311: line longer than 100 chars
[00:03:16] tidy error: /checkout/src/libcore/convert.rs:312: line longer than 100 chars
[00:03:16] tidy error: /checkout/src/libcore/convert.rs:313: line longer than 100 chars
[00:03:17] some tidy checks failed
[00:03:17] 
[00:03:17] 
[00:03:17] command did not execute successfully: "/checkout/obj/build/x86_64-unknown-linux-gnu/stage0-tools-bin/tidy" "/checkout/src" "/checkout/obj/build/x86_64-unknown-linux-gnu/stage0/bin/cargo" "--no-vendor" "--quiet"
[00:03:17] 
[00:03:17] 
[00:03:17] failed to run: /checkout/obj/build/bootstrap/debug/bootstrap test src/tools/tidy
[00:03:17] Build completed unsuccessfully in 0:00:44
[00:03:17] Build completed unsuccessfully in 0:00:44
[00:03:17] Makefile:67: recipe for target 'tidy' failed
[00:03:17] make: *** [tidy] Error 1
The command "stamp sh -x -c "$RUN_SCRIPT"" exited with 2.
travis_time:start:0d4c406a
$ date && (curl -fs --head https://google.com | grep ^Date: | sed 's/Date: //g' || true)
Wed Mar 20 22:31:26 UTC 2019
---
travis_time:end:2d247e6b:start=1553121086771121895,finish=1553121086776201799,duration=5079904
travis_fold:end:after_failure.3
travis_fold:start:after_failure.4
travis_time:start:1fc13f5e
$ ln -s . checkout && for CORE in obj/cores/core.*; do EXE=$(echo $CORE | sed 's|obj/cores/core\.[0-9]*\.!checkout!\(.*\)|\1|;y|!|/|'); if [ -f "$EXE" ]; then printf travis_fold":start:crashlog\n\033[31;1m%s\033[0m\n" "$CORE"; gdb --batch -q -c "$CORE" "$EXE" -iex 'set auto-load off' -iex 'dir src/' -iex 'set sysroot .' -ex bt -ex q; echo travis_fold":"end:crashlog; fi; done || true
travis_fold:end:after_failure.4
travis_fold:start:after_failure.5
travis_time:start:00fe8140
travis_time:start:00fe8140
$ cat ./obj/build/x86_64-unknown-linux-gnu/native/asan/build/lib/asan/clang_rt.asan-dynamic-i386.vers || true
cat: ./obj/build/x86_64-unknown-linux-gnu/native/asan/build/lib/asan/clang_rt.asan-dynamic-i386.vers: No such file or directory
travis_fold:end:after_failure.5
travis_fold:start:after_failure.6
travis_time:start:208c33f2
$ dmesg | grep -i kill

I'm a bot! I can only do what humans tell me to, so if this was not helpful or you have suggestions for improvements, please ping or otherwise contact @TimNN. (Feature Requests)

tesuji

Some nits on indentations.

src/libcore/convert.rs

steveklabnik · 2019-03-21T17:27:14Z

Hey hey! I won't have time until tomorrow to review this; @rust-lang/docs can you check it out in the meantime?

Thanks so much!

src/libcore/convert.rs

tesuji · 2019-03-21T17:57:39Z

One of the thing I find that it's hard to review docs PR because we don't have
visual built documentation of the changes right away.

Building whole rust documentation for small changes is overkill and it is so slow
to build for regular doc contributor.

rust-highfive · 2019-03-21T18:07:16Z

The job x86_64-gnu-llvm-6.0 of your PR failed on Travis (raw log). Through arcane magic we have determined that the following fragments from the build log may contain information about the problem.

Click to expand the log.

travis_time:end:1698e85c:start=1553190633769100723,finish=1553190754425390118,duration=120656289395
$ git checkout -qf FETCH_HEAD
travis_fold:end:git.checkout

Encrypted environment variables have been removed for security reasons.
See https://docs.travis-ci.com/user/pull-requests/#pull-requests-and-security-restrictions
$ export SCCACHE_BUCKET=rust-lang-ci-sccache2
$ export SCCACHE_REGION=us-west-1
$ export GCP_CACHE_BUCKET=rust-lang-ci-cache
Setting environment variables from .travis.yml
---

[00:03:36] travis_fold:start:tidy
travis_time:start:tidy
tidy check
[00:03:36] tidy error: /checkout/src/libcore/convert.rs:294: line longer than 100 chars
[00:03:38] some tidy checks failed
[00:03:38] 
[00:03:38] 
[00:03:38] command did not execute successfully: "/checkout/obj/build/x86_64-unknown-linux-gnu/stage0-tools-bin/tidy" "/checkout/src" "/checkout/obj/build/x86_64-unknown-linux-gnu/stage0/bin/cargo" "--no-vendor" "--quiet"
[00:03:38] 
[00:03:38] 
[00:03:38] failed to run: /checkout/obj/build/bootstrap/debug/bootstrap test src/tools/tidy
[00:03:38] Build completed unsuccessfully in 0:00:48
[00:03:38] Build completed unsuccessfully in 0:00:48
[00:03:38] make: *** [tidy] Error 1
[00:03:38] Makefile:67: recipe for target 'tidy' failed
The command "stamp sh -x -c "$RUN_SCRIPT"" exited with 2.
travis_time:start:1d036a5e
$ date && (curl -fs --head https://google.com | grep ^Date: | sed 's/Date: //g' || true)
Thu Mar 21 17:56:23 UTC 2019
---
travis_time:end:10f1c4b2:start=1553190985003954379,finish=1553190985010008759,duration=6054380
travis_fold:end:after_failure.3
travis_fold:start:after_failure.4
travis_time:start:0a8fde48
$ ln -s . checkout && for CORE in obj/cores/core.*; do EXE=$(echo $CORE | sed 's|obj/cores/core\.[0-9]*\.!checkout!\(.*\)|\1|;y|!|/|'); if [ -f "$EXE" ]; then printf travis_fold":start:crashlog\n\033[31;1m%s\033[0m\n" "$CORE"; gdb --batch -q -c "$CORE" "$EXE" -iex 'set auto-load off' -iex 'dir src/' -iex 'set sysroot .' -ex bt -ex q; echo travis_fold":"end:crashlog; fi; done || true
travis_fold:end:after_failure.4
travis_fold:start:after_failure.5
travis_time:start:101a45c2
travis_time:start:101a45c2
$ cat ./obj/build/x86_64-unknown-linux-gnu/native/asan/build/lib/asan/clang_rt.asan-dynamic-i386.vers || true
cat: ./obj/build/x86_64-unknown-linux-gnu/native/asan/build/lib/asan/clang_rt.asan-dynamic-i386.vers: No such file or directory
travis_fold:end:after_failure.5
travis_fold:start:after_failure.6
travis_time:start:045e0d2c
$ dmesg | grep -i kill

I'm a bot! I can only do what humans tell me to, so if this was not helpful or you have suggestions for improvements, please ping or otherwise contact @TimNN. (Feature Requests)

DevQps · 2019-03-21T18:12:47Z

@lzutao I can provide a tar or zip of the generated docs somehow but that isn't really ideal of course. Maybe it can be added as a downloadable asset at each Travis CI pipeline? I used to do that with Gitlab pipelines, not sure if Travis can do such a thing as well though.

DevQps · 2019-03-25T14:11:51Z

@ehuss @lzutao @steveklabnik Let me know if there's anything else I can do to improve things!

tesuji · 2019-03-25T14:48:14Z

This PR needs an review from Documentation team I think. You could ping any of them for requesting review.

steveklabnik · 2019-03-25T15:16:20Z

I'm planning on reviewing within the next few hours.

steveklabnik

Hey hey! This PR is great content-wise, I just have some formatting stuff. Please let me know if any of that isn't clear! As soon as the formatting is fixed, we can merge this in 👍

src/libcore/convert.rs

…ary lines.

DevQps · 2019-03-25T21:24:14Z

Hey hey! This PR is great content-wise, I just have some formatting stuff. Please let me know if any of that isn't clear! As soon as the formatting is fixed, we can merge this in 👍

@steveklabnik Thanks for your kind words! I fixed all the issues you brought up, thanks a lot for all the feedback :) Many of the things I was unaware of / didn't know so it will probably help me when I do some editing in the future as well.

I was wondering!: Are there are other things I could maybe help with? I am not sure if there are still documents to be reviewed? Or if there is some documentation that needs a test read / that needs some improvement? Now that I got the hang of it a little bit I would enjoy contributing some more! Let me know if there's anything I can do to help :)

EDIT: @lzutao @ehuss Thank you guys as well!

steveklabnik · 2019-03-26T19:18:38Z

Awesome, thanks!

@bors: r+ rollup

I was wondering!: Are there are other things I could maybe help with? I am not sure if there are still documents to be reviewed? Or if there is some documentation that needs a test read / that needs some improvement? Now that I got the hang of it a little bit I would enjoy contributing some more! Let me know if there's anything I can do to help :)

For sure! We have a T-docs tag with issues. Picking out one of them and writing some docs would be fantastic!

bors · 2019-03-26T19:18:39Z

📌 Commit 6c479c3 has been approved by steveklabnik

@steveklabnik

…ation, r=steveklabnik Improve the documentation for std::convert (From, Into, AsRef and AsMut) # Description In this PR I updated the documentation of From, Into, AsRef and AsMut, as well as the general std::convert module documentation. The discussion in rust-lang#59163 provided information that was not yet present in the docs, or was not expressed clearly enough. I tried to clarify the examples that were already present in the docs as well as add more information about considered best-practices that came out of the discussion in rust-lang#59163 @steveklabnik I hope I didn't change too much. This is an initial version! I will scan through everything tomorrow as well again to see if I made any typo's or errors, and maybe make some small changes here and there. All suggestions are welcome! closes rust-lang#59163

@ghost

Rollup of 7 pull requests Successful merges: - #59004 ([rustdoc] Improve "in parameters" search and search more generally) - #59026 (Fix moving text in search tabs headers) - #59197 (Exclude old book redirect stubs from search engines) - #59330 (Improve the documentation for std::convert (From, Into, AsRef and AsMut)) - #59424 (Fix code block display in portability element in dark theme) - #59427 (Link to PhantomData in NonNull documentation) - #59432 (Improve some compiletest documentation) Failed merges: r? @ghost

@ghost

Rollup of 7 pull requests Successful merges: - #59004 ([rustdoc] Improve "in parameters" search and search more generally) - #59026 (Fix moving text in search tabs headers) - #59197 (Exclude old book redirect stubs from search engines) - #59330 (Improve the documentation for std::convert (From, Into, AsRef and AsMut)) - #59424 (Fix code block display in portability element in dark theme) - #59427 (Link to PhantomData in NonNull documentation) - #59432 (Improve some compiletest documentation) Failed merges: r? @ghost

Initial version of the documentation change of std::convert.

71bdeb0

rust-highfive assigned shepmaster Mar 20, 2019

rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Mar 20, 2019

Reformatted the text such that the line length does not exceed 100.

49a9b34

tesuji reviewed Mar 21, 2019

View reviewed changes

src/libcore/convert.rs Outdated Show resolved Hide resolved

src/libcore/convert.rs Outdated Show resolved Hide resolved

Fixed indentation of list items.

d657d18

ehuss reviewed Mar 21, 2019

View reviewed changes

src/libcore/convert.rs Outdated Show resolved Hide resolved

tesuji reviewed Mar 21, 2019

View reviewed changes

src/libcore/convert.rs Outdated Show resolved Hide resolved

Christian added 2 commits March 21, 2019 18:42

Added back a reference to "the book"

a66fca4

Changed inline code by using a single quote.

d7fcd21

Wrapped a line such that it does not exceed 100 characters.

70ce4b1

steveklabnik suggested changes Mar 25, 2019

View reviewed changes

Formatting changes, including better wrapping and creating short summ…

6c479c3

…ary lines.

steveklabnik approved these changes Mar 26, 2019

View reviewed changes

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Mar 26, 2019

shepmaster assigned steveklabnik and unassigned shepmaster Mar 26, 2019

GuillaumeGomez mentioned this pull request Mar 26, 2019

Rollup of 7 pull requests #59447

Merged

bors merged commit 6c479c3 into rust-lang:master Mar 27, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve the documentation for std::convert (From, Into, AsRef and AsMut) #59330

Improve the documentation for std::convert (From, Into, AsRef and AsMut) #59330

DevQps commented Mar 20, 2019

rust-highfive commented Mar 20, 2019

rust-highfive commented Mar 20, 2019

tesuji left a comment

steveklabnik commented Mar 21, 2019

tesuji commented Mar 21, 2019 •

edited

Loading

rust-highfive commented Mar 21, 2019

DevQps commented Mar 21, 2019 •

edited

Loading

DevQps commented Mar 25, 2019

tesuji commented Mar 25, 2019

steveklabnik commented Mar 25, 2019

steveklabnik left a comment

DevQps commented Mar 25, 2019 •

edited

Loading

steveklabnik commented Mar 26, 2019

bors commented Mar 26, 2019

Improve the documentation for std::convert (From, Into, AsRef and AsMut) #59330

Improve the documentation for std::convert (From, Into, AsRef and AsMut) #59330

Conversation

DevQps commented Mar 20, 2019

Description

rust-highfive commented Mar 20, 2019

rust-highfive commented Mar 20, 2019

tesuji left a comment

Choose a reason for hiding this comment

steveklabnik commented Mar 21, 2019

tesuji commented Mar 21, 2019 • edited Loading

rust-highfive commented Mar 21, 2019

DevQps commented Mar 21, 2019 • edited Loading

DevQps commented Mar 25, 2019

tesuji commented Mar 25, 2019

steveklabnik commented Mar 25, 2019

steveklabnik left a comment

Choose a reason for hiding this comment

DevQps commented Mar 25, 2019 • edited Loading

steveklabnik commented Mar 26, 2019

bors commented Mar 26, 2019

tesuji commented Mar 21, 2019 •

edited

Loading

DevQps commented Mar 21, 2019 •

edited

Loading

DevQps commented Mar 25, 2019 •

edited

Loading