box: Add documentation for From impls

[daniellimws]

This is a part of #51430. A brief description of the behaviour and examples are added to the documentation.

I am not sure what sort of examples to put for the From for Pin as my code doesn't even manage to compile using the nightly build.

Somehow I feel that I missed out something so do let me know if more information is needed in the documentation or any of the examples require change.

[rust-highfive]

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

[sinkuu]

This one (and therefore From<&str>) allocates a RawVec.

[rust-highfive]

The job x86_64-gnu-llvm-5.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:02cd6382:start=1540813194435776745,finish=1540813249675946409,duration=55240169664
$ 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 SCCACHE_BUCKET=rust-lang-ci-sccache2
---
[00:51:40] .................................................................................................... 2200/4977
[00:51:44] .................................................................................................... 2300/4977
[00:51:48] .................................................................................................... 2400/4977
[00:51:52] .................................................................................................... 2500/4977
[00:51:55] .............................................................iiiiiiiii.............................. 2600/4977
[00:52:02] ............ii...................................................................................... 2800/4977
[00:52:05] .................................................................................................... 2900/4977
[00:52:09] .................................................................................................... 3000/4977
[00:52:11] .......i............................................................................................ 3100/4977
---
travis_time:start:test_codegen
Check compiletest suite=codegen mode=codegen (x86_64-unknown-linux-gnu -> x86_64-unknown-linux-gnu)
[01:05:24] 
[01:05:24] running 112 tests
[01:05:27] i..ii...iii.......i...i.........i..iii...........i.....i.....ii...i..i.ii..............i...ii..ii.i. 100/112
[01:05:28] test result: ok. 82 passed; 0 failed; 30 ignored; 0 measured; 0 filtered out
[01:05:28] 
[01:05:28]  finished in 3.551
[01:05:28] travis_fold:end:test_codegen
---
[01:16:01] error: no global memory allocator found but one is required; link to std or add #[global_allocator] to a static item that implements the GlobalAlloc trait.
[01:16:01] 
[01:16:01] 
[01:16:01] running 407 tests
[01:16:22] .....................F.............................................................................. 100/407
[01:16:55] .................................................................................................... 300/407
[01:17:11] .................................................................................................... 400/407
rustlib
72800 ./obj/build/x86_64-unknown-linux-gnu/stage0-sysroot/lib/rustlib/x86_64-unknown-linux-gnu
---
39608 ./obj/build/x86_64-unknown-linux-gnu/doc/book
39016 ./obj/build/x86_64-unknown-linux-gnu/stage2-tools/x86_64-unknown-linux-gnu/release/deps
38040 ./obj/build/x86_64-unknown-linux-gnu/test/ui/issues
37756 ./src/tools/lldb/www
37532 . 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:1a242b7c
travis_time:start:1a242b7c
$ 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:01ea6fe6
$ 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)

[alexcrichton]

Thanks! Looks like CI may be showing a typo remaining in a doc comment?

[TimNN]

Ping from triage @daniellimws: It looks like some changes are necessary to this PR.

[daniellimws]

I'm not really sure what went wrong. CI says there's an error with llvm but all that happens in this PR is documentation.

[alexcrichton]

The documentation examples are tested and I think one of the examples adder here failed compilation (output in the full logs)

[Mark-Simulacrum]

@daniellimws Do you think you'll have a chance to look at the failure on CI soon? I've pulled it out from the logs:

01:17:12] failures:
[01:17:12] 
[01:17:12] ---- boxed.rs - boxed::Box<[T]>::from (line 479) stdout ----
[01:17:12] error: expected expression, found `:`
[01:17:12]  --> boxed.rs:484:11
[01:17:12]   |
[01:17:12] 8 | println!({:?}, boxed_slice);
[01:17:12]   |           ^ expected expression
[01:17:12] 
[01:17:12] error: format argument must be a string literal
[01:17:12]  --> boxed.rs:484:10
[01:17:12]   |
[01:17:12] 8 | println!({:?}, boxed_slice);
[01:17:12]   |          ^^^^
[01:17:12] help: you might be missing a string literal to format with
[01:17:12]   |
[01:17:12] 8 | println!("{} {}", {:?}, boxed_slice);
[01:17:12]   |          ^^^^^^^^
[01:17:12] 
[01:17:12] thread 'boxed.rs - boxed::Box<[T]>::from (line 479)' panicked at 'couldn't compile the test', librustdoc/test.rs:332:13
[01:17:12] note: Run with `RUST_BACKTRACE=1` for a backtrace.
[01:17:12] 
[01:17:12] 
[01:17:12] failures:
[01:17:12]     boxed.rs - boxed::Box<[T]>::from (line 479)
[01:17:12] 

[daniellimws]

Really sorry about the hold up.

[Dylan-DPC-zz]

Errors from IMAGE=x86_64-gnu-llvm-5.0 job:

failures:

---- boxed.rs - boxed::Box<[T]>::from (line 480) stdout ----
error[E0283]: type annotations required: cannot resolve `std::boxed::Box<_>: std::convert::From<&[u8]>`
--> boxed.rs:483:19
|
6 | let boxed_slice = Box::from(slice);
|                   ^^^^^^^^^
|
= note: required by `std::convert::From::from`

thread 'boxed.rs - boxed::Box<[T]>::from (line 480)' panicked at 'couldn't compile the test', librustdoc/test.rs:323:13
note: Run with `RUST_BACKTRACE=1` for a backtrace.


failures:
boxed.rs - boxed::Box<[T]>::from (line 480)

test result: FAILED. 408 passed; 1 failed; 1 ignored; 0 measured; 0 filtered out

error: test failed, to rerun pass '--doc'

[TimNN]

Ping from triage @daniellimws: It looks like your PR failed on travis because one of the added examples fails to compile. (If you don't want to rely on travis / run the tests locally, you should be able to test the individual examples on play.rust-lang.org).

[TimNN]

Ping from triage @daniellimws: Do you think you'll be able to update your PR?

[Centril]

Tests passed so I think we can land this for now.

@bors r+ rollup

[bors]

📌 Commit 5e2bfda has been approved by Centril