improve Pin documentation

[RalfJung]

Incorporates a bunch of the documentation-related comments that came up when discussing Pin stabilization.

Cc @alexcrichton @withoutboats @cramertj @jonhoo

Fixes #58130

[rust-highfive]

r? @Mark-Simulacrum

(rust_highfive has picked a reviewer for you, use r? to override)

[Mark-Simulacrum]

This looks amazing! Thank you.

I think we may want to consider a beta backport as well if we can land this somewhat quickly so we ship these docs with the stabilization of Pin.

[jonhoo]

@RalfJung yup, looks better 👍

[rust-highfive]

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:0e1299a4:start=1550759715006557272,finish=1550759797359943775,duration=82353386503
$ 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:03:16] travis_fold:start:tidy
travis_time:start:tidy
tidy check
[00:03:16] tidy error: /checkout/src/libcore/pin.rs:18: line longer than 100 chars
[00:03:18] some tidy checks failed
[00:03:18] 
[00:03:18] 
[00:03:18] 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:18] 
[00:03:18] 
[00:03:18] failed to run: /checkout/obj/build/bootstrap/debug/bootstrap test src/tools/tidy
[00:03:18] Build completed unsuccessfully in 0:00:45
[00:03:18] Build completed unsuccessfully in 0:00:45
[00:03:18] make: *** [tidy] Error 1
[00:03:18] Makefile:68: recipe for target 'tidy' failed
The command "stamp sh -x -c "$RUN_SCRIPT"" exited with 2.
travis_time:start:3ab9fa20
$ date && (curl -fs --head https://google.com | grep ^Date: | sed 's/Date: //g' || true)
Thu Feb 21 14:40:05 UTC 2019
---
travis_time:end:159ae298:start=1550760006309266550,finish=1550760006313638772,duration=4372222
travis_fold:end:after_failure.3
travis_fold:start:after_failure.4
travis_time:start:1028cd60
$ 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:05e0012e
travis_time:start:05e0012e
$ 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:085606f0
$ 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)

[rust-highfive]

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:16ad4d2b:start=1550761639141063332,finish=1550761714006509873,duration=74865446541
$ 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:57:36]     Checking compiler_builtins v0.1.5
[00:57:37]  Documenting alloc v0.0.0 (/checkout/src/liballoc)
[00:57:42]     Finished release [optimized] target(s) in 37.24s
[00:57:43]  Documenting core v0.0.0 (/checkout/src/libcore)
[00:58:00] warning: `[Pin]` cannot be resolved, ignoring it...
[00:58:00]    --> src/libcore/marker.rs:605:61
[00:58:00]     |
[00:58:00] 605 | /// by controlling the behavior of pointers wrapped in the [`Pin`] wrapper,
[00:58:00]     |
[00:58:00] note: lint level defined here
[00:58:00]    --> src/libcore/lib.rs:63:9
[00:58:00]     |
---
[00:58:12]     Checking rustc_msan v0.0.0 (/checkout/src/librustc_msan)
[00:58:12]     Checking rustc_asan v0.0.0 (/checkout/src/librustc_asan)
[00:58:12]     Checking rustc_lsan v0.0.0 (/checkout/src/librustc_lsan)
[00:58:12]  Documenting std v0.0.0 (/checkout/src/libstd)
[00:58:19] error: `[Pin]` cannot be resolved, ignoring it...
[00:58:19]    --> /checkout/src/libcore/marker.rs:605:61
[00:58:19]     |
[00:58:19] 605 | /// by controlling the behavior of pointers wrapped in the [`Pin`] wrapper,
[00:58:19]     |
[00:58:19] note: lint level defined here
[00:58:19]    --> src/libstd/lib.rs:209:9
[00:58:19]     |
[00:58:19]     |
[00:58:19] 209 | #![deny(intra_doc_link_resolution_failure)]
[00:58:19]     |         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[00:58:19]     = help: to escape `[` and `]` characters, just add '\' before them like `\[` or `\]`
[00:58:19] 
[00:58:19] error: Could not document `std`.
[00:58:19] 
[00:58:19] Caused by:
[00:58:19]   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"' --cfg 'feature="std_detect_dlsym_getauxval"' --cfg 'feature="std_detect_file_io"' --markdown-css rust.css --markdown-no-toc --generate-redirect-pages --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)
[00:58:19] 
[00:58:19] 
[00:58:19] 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" "--generate-redirect-pages" "--index-page" "/checkout/src/doc/index.md"
[00:58:19] 
[00:58:19] 
[00:58:19] failed to run: /checkout/obj/build/bootstrap/debug/bootstrap doc
[00:58:19] Build completed unsuccessfully in 0:06:18
[00:58:19] Build completed unsuccessfully in 0:06:18
[00:58:19] Makefile:18: recipe for target 'all' failed
[00:58:19] make: *** [all] Error 1
The command "stamp sh -x -c "$RUN_SCRIPT"" exited with 2.
travis_time:start:16cd8ef9
$ date && (curl -fs --head https://google.com | grep ^Date: | sed 's/Date: //g' || true)
Thu Feb 21 16:07:03 UTC 2019
---
travis_time:end:1ad7246a:start=1550765224356712004,finish=1550765224363435729,duration=6723725
travis_fold:end:after_failure.3
travis_fold:start:after_failure.4
travis_time:start:16d6af00
$ 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:0d9bc12f
travis_time:start:0d9bc12f
$ 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:0f086856
$ 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)

[RalfJung]

All right, I think I resolved all comments. Let's land this! p=1 because we want to backport it.

@bors r=Mark-Simulacrum p=1

[bors]

📌 Commit 497439c has been approved by Mark-Simulacrum

[bors]

🌲 The tree is currently closed for pull requests below priority 99, this pull request will be tested once the tree is reopened

[Centril]

@bors p=30

[bors]

⌛ Testing commit 497439c with merge c6fd027...

[bors]

☀️ Test successful - checks-travis, status-appveyor
Approved by: Mark-Simulacrum
Pushing c6fd027 to master...

[bors]

☀️ Test successful - checks-travis, status-appveyor
Approved by: Mark-Simulacrum
Pushing c6fd027 to master...

[RalfJung]

@Mark-Simulacrum Do I have to do anything for the beta backport, or are you taking care of that?

[Mark-Simulacrum]

The release team will take care of it.