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

Expand docs for `TryFrom` and `TryInto`. #58015

Open
wants to merge 5 commits into
base: master
from

Conversation

Projects
None yet
7 participants
@icefoxen
Copy link
Contributor

icefoxen commented Jan 31, 2019

The examples are still lacking for now, both for module docs and for methods/impl's. Will be adding those in further pushes.

Should hopefully resolve the doc concern in #33417 when finished?

Started expanding docs for `TryFrom` and `TryInto`.
The examples are still lacking for now, both for module docs
and for methods/impl's.
@rust-highfive

This comment has been minimized.

Copy link
Collaborator

rust-highfive commented Jan 31, 2019

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @sfackler (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.

Add basic docs to integer TryFrom impl macros.
They're not as good as `From` 'cause they don't stringify
the types and generate examples and so on, but it's a start.
@rust-highfive

This comment has been minimized.

Copy link
Collaborator

rust-highfive commented Jan 31, 2019

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:02bf2da0:start=1548897658301142413,finish=1548897659328024003,duration=1026881590
$ 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
Setting environment variables from .travis.yml
$ export IMAGE=x86_64-gnu-llvm-6.0
---
[00:04:36] tidy error: /checkout/src/libcore/convert.rs:418: trailing whitespace
[00:04:38] some tidy checks failed
[00:04:38] 
[00:04:38] 
[00:04: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:04:38] 
[00:04:38] 
[00:04:38] failed to run: /checkout/obj/build/bootstrap/debug/bootstrap test src/tools/tidy
[00:04:38] Build completed unsuccessfully in 0:00:45
[00:04:38] Build completed unsuccessfully in 0:00:45
[00:04:38] make: *** [tidy] Error 1
[00:04:38] Makefile:68: recipe for target 'tidy' failed
The command "stamp sh -x -c "$RUN_SCRIPT"" exited with 2.
travis_time:start:29c3f4e0
$ date && (curl -fs --head https://google.com | grep ^Date: | sed 's/Date: //g' || true)
Thu Jan 31 01:25:48 UTC 2019
---
travis_time:end:1450b116:start=1548897949908823832,finish=1548897949913596563,duration=4772731
travis_fold:end:after_failure.3
travis_fold:start:after_failure.4
travis_time:start:1589b860
$ 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:01996710
travis_time:start:01996710
$ 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:05c6ea95
$ 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)

Show resolved Hide resolved src/libcore/convert.rs Outdated
@rust-highfive

This comment has been minimized.

Copy link
Collaborator

rust-highfive commented Feb 1, 2019

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:294fb0e0:start=1548989471035466598,finish=1548989546259844475,duration=75224377877
$ 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
Setting environment variables from .travis.yml
$ export IMAGE=x86_64-gnu-llvm-6.0
---
[01:01:58]     Checking compiler_builtins v0.1.5
[01:02:00]  Documenting alloc v0.0.0 (/checkout/src/liballoc)
[01:02:04]     Finished release [optimized] target(s) in 36.67s
[01:02:05]  Documenting core v0.0.0 (/checkout/src/libcore)
[01:02:22] warning: `[try_from]` cannot be resolved, ignoring it...
[01:02:22]     |
[01:02:22]     |
[01:02:22] 402 | /// - [`try_from`] is reflexive, which means that `TryFrom<T> for T`
[01:02:22]     |
[01:02:22] note: lint level defined here
[01:02:22]    --> src/libcore/lib.rs:65:9
[01:02:22]     |
---
[01:02:32]     Checking rustc_tsan v0.0.0 (/checkout/src/librustc_tsan)
[01:02:32]     Checking rustc_lsan v0.0.0 (/checkout/src/librustc_lsan)
[01:02:32]     Checking rustc_asan v0.0.0 (/checkout/src/librustc_asan)
[01:02:32]  Documenting std v0.0.0 (/checkout/src/libstd)
[01:02:39] error: `[TryInto]` cannot be resolved, ignoring it...
[01:02:39]     |
[01:02:39]     |
[01:02:39] 385 | /// way under some circumstances. It is the reciprocal of [`TryInto`].
[01:02:39]     |
[01:02:39] note: lint level defined here
[01:02:39]    --> src/libstd/lib.rs:211:9
[01:02:39]     |
[01:02:39]     |
[01:02:39] 211 | #![deny(intra_doc_link_resolution_failure)]
[01:02:39]     |         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[01:02:39]     = help: to escape `[` and `]` characters, just add '\' before them like `\[` or `\]`
[01:02:39] 
[01:02:39] error: `[try_from]` cannot be resolved, ignoring it...
[01:02:39]     |
[01:02:39]     |
[01:02:39] 402 | /// - [`try_from`] is reflexive, which means that `TryFrom<T> for T`
[01:02:39]     |
[01:02:39]     = help: to escape `[` and `]` characters, just add '\' before them like `\[` or `\]`
[01:02:39] 
[01:02:39] error: Could not document `std`.
[01:02:39] error: Could not document `std`.
[01:02:39] 
[01:02:39] Caused by:
[01:02:39]   process didn't exit successfully: `/checkout/obj/build/bootstrap/debug/rustdoc --crate-name std src/libstd/lib.rs --color always --target x86_64-unknown-linux-gnu -o /checkout/obj/build/x86_64-unknown-linux-gnu/stage1-std/x86_64-unknown-linux-gnu/doc --cfg 'feature="backtrace"' --cfg 'feature="backtrace-sys"' --cfg 'feature="compiler_builtins"' --cfg 'feature="compiler_builtins_c"' --cfg 'feature="default"' --cfg 'feature="panic-unwind"' --cfg 'feature="panic_unwind"' --markdown-css rust.css --markdown-no-toc --index-page /checkout/src/doc/index.md -L dependency=/checkout/obj/build/x86_64-unknown-linux-gnu/stage1-std/x86_64-unknown-linux-gnu/release/deps -L dependency=/checkout/obj/build/x86_64-unknown-linux-gnu/stage1-std/release/deps --extern alloc=/checkout/obj/build/x86_64-unknown-linux-gnu/stage1-std/x86_64-unknown-linux-gnu/release/deps/liballoc-9e6c0311b71511c6.rmeta --extern backtrace_sys=/checkout/obj/build/x86_64-unknown-linux-gnu/stage1-std/x86_64-unknown-linux-gnu/release/deps/libbacktrace_sys-f13b165ed9b4dd57.rmeta --extern compiler_builtins=/checkout/obj/build/x86_64-unknown-linux-gnu/stage1-std/x86_64-unknown-linux-gnu/release/deps/libcompiler_builtins-d54fe968dea87029.rmeta --extern core=/checkout/obj/build/x86_64-unknown-linux-gnu/stage1-std/x86_64-unknown-linux-gnu/release/deps/libcore-84e5b9599b1b7754.rmeta --extern libc=/checkout/obj/build/x86_64-unknown-linux-gnu/stage1-std/x86_64-unknown-linux-gnu/release/deps/liblibc-a69fda92b07aedd5.rmeta --extern panic_abort=/checkout/obj/build/x86_64-unknown-linux-gnu/stage1-std/x86_64-unknown-linux-gnu/release/deps/libpanic_abort-349a3e5cce9f18ee.rmeta --extern panic_unwind=/checkout/obj/build/x86_64-unknown-linux-gnu/stage1-std/x86_64-unknown-linux-gnu/release/deps/libpanic_unwind-d7c48504ff1056b6.rmeta --extern rustc_demangle=/checkout/obj/build/x86_64-unknown-linux-gnu/stage1-std/x86_64-unknown-linux-gnu/release/deps/librustc_demangle-20814bca47e9a554.rmeta --extern rustc_asan=/checkout/obj/build/x86_64-unknown-linux-gnu/stage1-std/x86_64-unknown-linux-gnu/release/deps/librustc_asan-8bc4c4bf1d4ec8f0.rmeta --extern rustc_lsan=/checkout/obj/build/x86_64-unknown-linux-gnu/stage1-std/x86_64-unknown-linux-gnu/release/deps/librustc_lsan-0814373332ff833c.rmeta --extern rustc_msan=/checkout/obj/build/x86_64-unknown-linux-gnu/stage1-std/x86_64-unknown-linux-gnu/release/deps/librustc_msan-655667bc8a1522d0.rmeta --extern rustc_tsan=/checkout/obj/build/x86_64-unknown-linux-gnu/stage1-std/x86_64-unknown-linux-gnu/release/deps/librustc_tsan-5756fbda854daecf.rmeta --extern unwind=/checkout/obj/build/x86_64-unknown-linux-gnu/stage1-std/x86_64-unknown-linux-gnu/release/deps/libunwind-5e31c590860d0940.rmeta` (exit code: 1)
[01:02:39] 
[01:02:39] 
[01:02:39] command did not execute successfully: "/checkout/obj/build/x86_64-unknown-linux-gnu/stage0/bin/cargo" "rustdoc" "--target" "x86_64-unknown-linux-gnu" "-j" "4" "--release" "--locked" "--color" "always" "--features" "panic-unwind backtrace" "--manifest-path" "/checkout/src/libstd/Cargo.toml" "-Z" "unstable-options" "-p" "std" "--" "--markdown-css" "rust.css" "--markdown-no-toc" "--index-page" "/checkout/src/doc/index.md"
[01:02:39] 
[01:02:39] 
[01:02:39] failed to run: /checkout/obj/build/bootstrap/debug/bootstrap doc
[01:02:39] Build completed unsuccessfully in 0:06:13
[01:02:39] Build completed unsuccessfully in 0:06:13
[01:02:39] Makefile:18: recipe for target 'all' failed
[01:02:39] make: *** [all] Error 1
The command "stamp sh -x -c "$RUN_SCRIPT"" exited with 2.
travis_time:start:11fb2434
$ date && (curl -fs --head https://google.com | grep ^Date: | sed 's/Date: //g' || true)
Fri Feb  1 03:55:14 UTC 2019

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)

@Dylan-DPC

This comment has been minimized.

Copy link
Member

Dylan-DPC commented Feb 11, 2019

ping from triage @icefoxen you need to resolve the failing tests.

@icefoxen

This comment has been minimized.

Copy link
Contributor Author

icefoxen commented Feb 12, 2019

Thanks @dpc I will gnaw on them when I get a chance.

@dpc

This comment has been minimized.

Copy link
Contributor

dpc commented Feb 12, 2019

Wrong dpc. @Dylan-DPC :) . But I like what's going on here, too. 🎉

@icefoxen

This comment has been minimized.

Copy link
Contributor Author

icefoxen commented Feb 12, 2019

There's too many dpc's around!

@icefoxen

This comment has been minimized.

Copy link
Contributor Author

icefoxen commented Feb 13, 2019

Ok it's time to finish pushing this through. It currently conflicts with #58302 but the actual differences are trivial. If that one gets accepted I'll update the docs in this PR to match what we need.

@rust-highfive

This comment has been minimized.

Copy link
Collaborator

rust-highfive commented Feb 13, 2019

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:038c1719:start=1550082648400920453,finish=1550082822735458805,duration=174334538352
$ 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
Setting environment variables from .travis.yml
$ export IMAGE=x86_64-gnu-llvm-6.0
---
travis_time:start:test_debuginfo
Check compiletest suite=debuginfo mode=debuginfo-both (x86_64-unknown-linux-gnu -> x86_64-unknown-linux-gnu)
[01:13:56] 
[01:13:56] running 119 tests
[01:14:21] .iiiii...i.....i..i...i..i.i..i.ii...i.....i..i....i..........iiii..........i...ii...i.......ii.i.i. 100/119
[01:14:25] i......iii.i.....ii
[01:14:25] 
[01:14:25]  finished in 28.738
[01:14:25] travis_fold:end:test_debuginfo

---
[01:24:55] 
[01:24:55]    Doc-tests core
[01:25:00] 
[01:25:00] running 2253 tests
[01:25:11] ....i..iiiiii....................................................................................... 100/2253
[01:25:22] .............................................................................F...................... 200/2253
[01:25:50] .................................................................................................... 400/2253
[01:26:02] .................................................................................................... 500/2253
[01:26:13] .................................................................................................... 600/2253
[01:26:25] .................................................................................................... 700/2253
---
[01:29:40] ---- convert.rs - convert::TryFrom (line 414) stdout ----
[01:29:40] error[E0599]: no function or associated item named `try_from` found for type `i32` in the current scope
[01:29:40]   --> convert.rs:423:31
[01:29:40]    |
[01:29:40] 12 | let try_smaller_number = i32::try_from(big_number);
[01:29:40]    |                          |
[01:29:40]    |                          function or associated item not found in `i32`
[01:29:40]    |
[01:29:40]    = help: items from traits can only be used if the trait is in scope
[01:29:40]    = help: items from traits can only be used if the trait is in scope
[01:29:40] help: the following trait is implemented but not in scope, perhaps add a `use` for it:
[01:29:40]    |
[01:29:40] 3  | use std::convert::TryFrom;
[01:29:40] 
[01:29:40] error[E0599]: no function or associated item named `try_from` found for type `i32` in the current scope
[01:29:40]   --> convert.rs:427:42
[01:29:40]    |
[01:29:40]    |
[01:29:40] 16 | let try_successful_smaller_number = i32::try_from(3);
[01:29:40]    |                                     |
[01:29:40]    |                                     function or associated item not found in `i32`
[01:29:40]    |
[01:29:40]    = help: items from traits can only be used if the trait is in scope
[01:29:40]    = help: items from traits can only be used if the trait is in scope
[01:29:40] help: the following trait is implemented but not in scope, perhaps add a `use` for it:
[01:29:40]    |
[01:29:40] 3  | use std::convert::TryFrom;
[01:29:40] 
[01:29:40] 
[01:29:40] thread 'convert.rs - convert::TryFrom (line 414)' panicked at 'couldn't compile the test', src/librustdoc/test.rs:354:13
[01:29:40] 
[01:29:40] 
[01:29:40] failures:
[01:29:40]     convert.rs - convert::TryFrom (line 414)
[01:29:40]     convert.rs - convert::TryFrom (line 414)
[01:29:40] 
[01:29:40] test result: FAILED. 2242 passed; 1 failed; 10 ignored; 0 measured; 0 filtered out
[01:29:40] 
[01:29:40] error: test failed, to rerun pass '--doc'
[01:29:40] 
[01:29:40] 
[01:29:40] command did not execute successfully: "/checkout/obj/build/x86_64-unknown-linux-gnu/stage0/bin/cargo" "test" "--target" "x86_64-unknown-linux-gnu" "-j" "4" "--release" "--locked" "--color" "always" "--features" "panic-unwind backtrace" "--manifest-path" "/checkout/src/libstd/Cargo.toml" "-p" "core" "--" "--quiet"
[01:29:40] 
[01:29:40] 
[01:29:40] failed to run: /checkout/obj/build/bootstrap/debug/bootstrap test
[01:29:40] Build completed unsuccessfully in 0:27:02
[01:29:40] Build completed unsuccessfully in 0:27:02
[01:29:40] Makefile:48: recipe for target 'check' failed
[01:29:40] make: *** [check] Error 1
The command "stamp sh -x -c "$RUN_SCRIPT"" exited with 2.
travis_time:start:01e1bf4e
$ date && (curl -fs --head https://google.com | grep ^Date: | sed 's/Date: //g' || true)
Wed Feb 13 20:03:32 UTC 2019
---
travis_time:end:0302c300:start=1550088214066318358,finish=1550088214070848906,duration=4530548
travis_fold:end:after_failure.3
travis_fold:start:after_failure.4
travis_time:start:05b62ef8
$ 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:0ab13b29
travis_time:start:0ab13b29
$ 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:0bddaf7f
$ 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)

Slowly figuring out how rustdoc actually works.
Unfortunately trying to run doctests on my local machine is
not really faster than letting Travis do it...
@SimonSapin

This comment has been minimized.

Copy link
Contributor

SimonSapin commented Feb 14, 2019

Thank you for helping push this forward!

(I’ve edited the PR description, resolve followed by an issue number is special on GitHub and causes that issue to be closed when the PR is merged.)

@icefoxen

This comment has been minimized.

Copy link
Contributor Author

icefoxen commented Feb 14, 2019

@SimonSapin Thanks! I knew about that behavior but am never 100% sure what does and does not trigger it. Alas.

@SimonSapin

This comment has been minimized.

Copy link
Contributor

SimonSapin commented Feb 14, 2019

It’s documented in https://help.github.com/articles/closing-issues-using-keywords/. And, since… more recently than the behavior has existed, those keywords have a dotted underline and an explanation tooltip when they are interpreted specially. See for example #58407.

@icefoxen icefoxen changed the title [WIP] Started expanding docs for `TryFrom` and `TryInto`. Expand docs for `TryFrom` and `TryInto`. Feb 14, 2019

@icefoxen

This comment has been minimized.

Copy link
Contributor Author

icefoxen commented Feb 14, 2019

Ok. Docs done, tidy has no complaints, doctests run successfully.

r?

@icefoxen icefoxen referenced this pull request Feb 14, 2019

Open

Tracking issue for TryFrom/TryInto traits #33417

1 of 3 tasks complete
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment