Add an explicit "How can I implement `Eq`" doc section

Building on the example in PartialEq.

Add an explicit "How can I implement `PartialEq`"? doc section

Including an example of a custom implementation. I put this expanded
section after the `Derivable` section to encourage use of that first.

Reorder `Copy` doc sections

The new order puts all the "when" questions together and puts the "how"
question with the "derivable" section. So you have to scroll past (and
hopefully read) the can/cannot/should caveats and guidelines to get to
the information about how to actually go about doing it once you've
determined that you can and should, with derivable information first so
that you can just use the derived implementation if that applies.

Previous order:

* General explanation
* When can my type be `Copy`?
* How can I implement `Copy`?
* When can my type _not_ be `Copy`?
* When should my type be `Copy`?
* Derivable

New order:

* General explanation
* When can my type be `Copy`?
* When can my type _not_ be `Copy`?
* When should my type be `Copy`?
* Derivable
* How can I implement `Copy`?

Make `Derivable` header be an h2 instead of an h1

This matches the other subsections.

`derive` explanation for PartialOrd should match that for Ord

I think these just got out of sync, but both use a lexicographic
ordering.

Relevant commits in the history of these explanations:
* 8b81f76 on 2015-06-30
* e22770b on 2016-02-09

Add explanations about what derived trait implementations do

Auto merge of #33098 - raphlinus:master, r=alexcrichton

Efficient trie lookup for boolean Unicode properties

Replace binary search of ranges with trie lookup using leaves of
64-bit bitmap chunks. Benchmarks suggest this is approximately 10x
faster than the bsearch approach.

Auto merge of #31457 - lambda:rtabort-use-libc-abort, r=alexcrichton

Use libc::abort, not intrinsics::abort, in rtabort!

intrinsics::abort compiles down to an illegal instruction, which on
Unix-like platforms causes the process to be killed with SIGILL.  A more
appropriate way to kill the process would be SIGABRT; this indicates
better that the runtime has explicitly aborted, rather than some kind of
compiler bug or architecture mismatch that SIGILL might indicate.

For rtassert!, replace this with libc::abort.  libc::abort raises
SIGABRT, but is defined to do so in such a way that it will terminate
the process even if SIGABRT is currently masked or caught by a signal
handler that returns.

On non-Unix platforms, retain the existing behavior.  On Windows we
prefer to avoid depending on the C runtime, and we need a fallback for
any other platforms that may be defined.  An alternative on Windows
would be to call TerminateProcess, but this seems less essential than
switching to using SIGABRT on Unix-like platforms, where it is common
for the process-killing signal to be printed out or logged.

This is a [breaking-change] for any code that depends on the exact
signal raised to abort a process via rtabort!

cc #31273
cc #31333

Use libc::abort, not intrinsics::abort, in rtabort!

intrinsics::abort compiles down to an illegal instruction, which on
Unix-like platforms causes the process to be killed with SIGILL.  A more
appropriate way to kill the process would be SIGABRT; this indicates
better that the runtime has explicitly aborted, rather than some kind of
compiler bug or architecture mismatch that SIGILL might indicate.

For rtassert!, replace this with libc::abort.  libc::abort raises
SIGABRT, but is defined to do so in such a way that it will terminate
the process even if SIGABRT is currently masked or caught by a signal
handler that returns.

On non-Unix platforms, retain the existing behavior.  On Windows we
prefer to avoid depending on the C runtime, and we need a fallback for
any other platforms that may be defined.  An alternative on Windows
would be to call TerminateProcess, but this seems less essential than
switching to using SIGABRT on Unix-like platforms, where it is common
for the process-killing signal to be printed out or logged.

This is a [breaking-change] for any code that depends on the exact
signal raised to abort a process via rtabort!

cc #31273
cc #31333

Auto merge of #33765 - alex-ozdemir:master, r=Manishearth

Added a `rustdoc` shortcut for collapse/expand all

Now when the user presses the "+" key all sections will collapse/expand.

Also added a note to the help screen which describes this behavior.

This required increasing the height of the help screen.

Auto merge of #33752 - mrhota:internal_docs, r=steveklabnik

Internal docs

This PR is a rebase of #30621. That PR can be closed.

CC @ticki @Aatch @cyplo

Auto merge of #33767 - sfackler:panic-hook-docs, r=alexcrichton

Mention that the panic hook will always run

r? @alexcrichton

cc @tomaka

Improve internal documentation and code style

Fix some code layout, remove some unnecessary returns, fix typos,
punctuation, and comment consistency.

Auto merge of #33768 - Manishearth:rollup, r=Manishearth

Rollup of 7 pull requests

- Successful merges: #33578, #33679, #33743, #33746, #33747, #33750, #33757
- Failed merges:

Rollup merge of #33757 - GuillaumeGomez:simd, r=steveklabnik

Update simd syntax

r? @steveklabnik

Rollup merge of #33750 - alx741:fix_typo, r=Manishearth

book: ownership: fix typo

The sentence ends there, so a comma is required.

See:
http://english.stackexchange.com/questions/1469/when-ending-a-list-with-etc-should-there-be-a-comma-before-etc

Rollup merge of #33747 - postmodern:patch-2, r=Manishearth

Clarify the English translation of `?Sized`

* It wasn't clear whether `?Sized` meant "not `Sized`" or "`Sized` or not `Sized`". According to #rust IRC, it does indeed mean "`Sized` or not `Sized`".
* Use the same language as [Trait std::marker::Sized](https://doc.rust-lang.org/std/marker/trait.Sized.html) about how `Sized` is implicitly bound.
* Refer to the syntax as `?Sized`, since it's currently the only allowed trait that can follow `?`.

Rollup merge of #33746 - dns2utf8:doc_sort_memory, r=steveklabnik

Clarify docs for sort(&mut self)

I documented the memory usage like noted in this issue:
  * Document memory usage of sort() family of functions #33419

Rollup merge of #33743 - royalstream:royalstream-stack-doc, r=steveklabnik

Book: small improvement to a table to make it clearer

This table is used as an example of four heap values where two of them got deallocated leaving a gap.
It also has stack variables.
Instead of four stack variables I propose three, that way there's no misleading connection between the number of stack variables and heap variables.
But more importantly: three of the four stack variables had the same name (**y**) which could be confusing to a beginner, I changed this as well.

Rollup merge of #33679 - Manishearth:rustdoc-readmore-impls, r=alexcrichton

rustdoc: Add doc snippets for trait impls, with a read more link

The read more link only appears if the documentation is more than one line long.


It currently does not appear on non-defaulted methods, since you can document them directly. I could make it so that default documentation gets forwarded if regular docs don't exist.

Fixes #33672

r? @alexcrichton

cc @steveklabnik

Rollup merge of #33578 - durka:patch-21, r=alexcrichton

update tracking issue for once_poison

The tracking issue for once_poison was noted as #31688 which was closed, so it now points to the new #33577.

Auto merge of #33625 - alexcrichton:rustbuild-moar-tests, r=aturon

rustbuild: Touch up some test suites

This adds in some missing test suites, primarily a few pretty suites. It also starts optimizing tests by default as the current test suite does, but also recognizes `--disable-optimize-tests`.

Currently the optimization of tests isn't recognized by crate tests because Cargo doesn't support the ability to compile an unoptimized test suite against an optimized library. Perhaps a feature to add, though!

Added a `rustdoc` shortcut for collapse/expand all

Now when the user presses the "+" key all sections will collapse/expand.

Also added a note to the help screen which describes this behavior.

Wording changes

* Use "special bound syntax" instead of "special syntax". `?Sized` is technically a "bound", but `?Sized` is specialized syntax that _only_ works with `Sized`, and no other Trait.
* Replace "constant size" with "sized".

update tracking issue for once_poison

The tracking issue for once_poison was noted as #31688 which was closed, so it now points to the new #33577.

Auto merge of #33758 - GuillaumeGomez:rollup, r=Manishearth

Rollup of 6 pull requests

- Successful merges: #33668, #33676, #33683, #33734, #33739, #33745
- Failed merges: #33578

rustc: Fix again order-dependence in extern crate

Originally fixed in #29961 the bug was unfortunately still present in the face
of crates using `#[macro_use]`. This commit refactors for the two code paths to
share common logic to ensure that they both pick up the same bug fix.

Closes #33762

Auto merge of #33318 - alexcrichton:hashmap-seed, r=aturon

std: Cache HashMap keys in TLS

This is a rebase and extension of #31356 where we not only cache the keys in
thread local storage but we also bump each key every time a new `HashMap` is
created. This should give us a nice speed bost in creating hash maps along with
retaining the property that all maps have a nondeterministic iteration order.

Closes #27243

Auto merge of #33378 - oli-obk:fix/registry_args, r=Manishearth

fix Registry::args for plugins loaded with --extra-plugins

r? @Manishearth

Clarify docs for sort(&mut self)

Rollup merge of #33745 - postmodern:patch-1, r=steveklabnik

Clarify wording in `transmute` example

* Change "four eights" to "four u8s"
* Change "a 32" to "a u32"

Rollup merge of #33739 - GuillaumeGomez:error-code-tests, r=Manishearth

Add new error code tests

r? @steveklabnik

Rollup merge of #33734 - luqmana:33387-mir_fat_ptr_coerce, r=arielb1

[MIR] Add PointerCast for Unsize casts of fat pointers.

Fixes #33387.

r? @eddyb

Rollup merge of #33683 - sanxiyn:paren-span, r=nikomatsakis

Preserve span when lowering ExprKind::Paren

Fix #33681.

Rollup merge of #33676 - rkruppe:e0509-exact-words, r=sanxiyn

Reword the short diagnostic for E0509

Saying that a type *implements* a trait is much more idiomatic than saying it *defines* the trait.

Rollup merge of #33668 - dns2utf8:catch_thread, r=steveklabnik

Catch thread in example

Since this is an example, the code will be copied by many people and should be over correct.

?r @steveklabnik

Update simd syntax

Update tests

Auto merge of #33729 - alexcrichton:patch-libbacktrace, r=sfackler

std: Backport a libbacktrace soundness fix

This is a backport of gcc-mirror/gcc@047a1c2f which is a soundness fix for when
a backtrace is generated on executables that do not have debug information.

Auto merge of #33553 - alexcrichton:cdylibs, r=brson

rustc: Add a new crate type, cdylib

This commit is an implementation of [RFC 1510] which adds a new crate type,
`cdylib`, to the compiler. This new crate type differs from the existing `dylib`
crate type in a few key ways:

* No metadata is present in the final artifact
* Symbol visibility rules are the same as executables, that is only reachable
  `extern` functions are visible symbols
* LTO is allowed
* All libraries are always linked statically

This commit is relatively simple by just plubming the compiler with another
crate type which takes different branches here and there. The only major change
is an implementation of the `Linker::export_symbols` function on Unix which now
actually does something. This helps restrict the public symbols from a cdylib on
Unix.

With this PR a "hello world" `cdylib` is 7.2K while the same `dylib` is 2.4MB,
which is some nice size savings!

[RFC 1510]: https://github.com/rust-lang/rfcs/pull/1510

Closes #33132

Mention that the panic hook will always run

Auto merge of #33358 - michaelwoerister:debuginfo-methods, r=eddyb

debuginfo: Make DW_TAG_subroutine DIEs for inherent methods children of their self-type DIEs.

Fixes https://github.com/rust-lang/rust/issues/33192

book: ownership: fix typo

Grammar change

Keep line-width within 80 columns

Clarify the English translation of `?Sized`

* It wasn't clear whether `?Sized` meant "not `Sized`" or "`Sized` or not `Sized`". According to #rust IRC, it does indeed mean "`Sized` or not `Sized`".
* Use the same language as [Trait std::marker::Sized](https://doc.rust-lang.org/std/marker/trait.Sized.html) about how `Sized` is implicitly bound.

std: Cache HashMap keys in TLS

This is a rebase and extension of #31356 where we cache the keys in thread local
storage. This should give us a nice speed bost in creating hash maps along with
mostly retaining the property that all maps have a nondeterministic iteration
order.

Closes #27243

Auto merge of #33103 - ranma42:escape-unicode-last, r=alexcrichton

Implement `last` for `EscapeUnicode`

The implementation is quite trivial as the last character is always `'{'`.
As a side-effect it also improves the implementation of `last` for `EscapeUnicode`.

Part of #24214, split from #31049.

Maybe this (and the other changes that I will split from #31049) should wait for a test like `ed_iterator_specializations` to be added. Would it be sufficient to do the same for each possible escape length?

debuginfo: Make DW_TAG_subroutine DIEs for inherent methods children of their self-type DIEs.

Mark the metadata symbol as reachable to fix OSX not finding dylibs.

rustc: Add a new crate type, cdylib

This commit is an implementation of [RFC 1510] which adds a new crate type,
`cdylib`, to the compiler. This new crate type differs from the existing `dylib`
crate type in a few key ways:

* No metadata is present in the final artifact
* Symbol visibility rules are the same as executables, that is only reachable
  `extern` functions are visible symbols
* LTO is allowed
* All libraries are always linked statically

This commit is relatively simple by just plubming the compiler with another
crate type which takes different branches here and there. The only major change
is an implementation of the `Linker::export_symbols` function on Unix which now
actually does something. This helps restrict the public symbols from a cdylib on
Unix.

With this PR a "hello world" `cdylib` is 7.2K while the same `dylib` is 2.4MB,
which is some nice size savings!

[RFC 1510]: https://github.com/rust-lang/rfcs/pull/1510

Closes #33132

Catch thread in example

 - Consume result of thread join()
 - Add link to threading model

Clarify wording in `transmute` example

* Change "four eights" to "four u8s"
* Change "a 32" to "a u32"

std: Update libbacktrace for a soundness fix

This updates the vendor'd libbacktrace source to tpick up
gcc-mirror/gcc@047a1c2f which is a soundness fix for when a backtrace is
generated on executables that do not have debug information.

Book: small improvement to a table to make it clearer

Auto merge of #33742 - Manishearth:rollup, r=Manishearth

Rollup of 10 pull requests

- Successful merges: #33353, #33611, #33696, #33698, #33705, #33708, #33712, #33720, #33721, #33730
- Failed merges:

Rollup merge of #33730 - jseyfried:fix_macro_backtrace_diagnostics, r=nikomatsakis

Fix macro expansion backtrace diagnostics

Fixes #33704.
r? @nikomatsakis

Rollup merge of #33721 - royalstream:royalstream-doc-highlights, r=Manishearth

Rust syntax coloring for some ignore, should-panic and no-run snippets.

In the book, some code blocks were missing the `rust` specifier which is needed for them to highlight correctly.

Rollup merge of #33720 - mark-summerfield:patch-1, r=steveklabnik

Clarified that `let(mut x, y) =` only makes x mutable, not y

Closes #33716

Rollup merge of #33712 - jseyfried:fix_expanded_expr_span_bug, r=nrc

Fix bug in macro expression spans

Fix a bug in macro expression spans.
r? @nrc

Rollup merge of #33708 - nham:zero-elided-lifetimes, r=sanxiyn

Only print parameters with elided lifetimes in elision error messages.

When displaying the function parameters for a lifetime elision error message,
this changes it to first filter out the parameters that don't have elided
lifetimes.

Fixes #30255.

Rollup merge of #33705 - lqd:rustdoc-version-tooltip, r=GuillaumeGomez

rustdoc: Make the #[stable(since)] version attribute clearer with a tooltip

Rustdoc's new 'since' version placement only shows the version number in which the item was marked stable. This gains space but might make the meaning of this version string less clear in the docs, so I tried to bring some explicitness in a tooltip.

Rollup merge of #33698 - alexcrichton:update-libc, r=japaric

std: Update libc submodule

Brings in a fix where `-lutil` is no longer passed for musl targets, lifting the
need for a musl toolchain to be installed again.

Closes #33608

Rollup merge of #33696 - nham:add-test-21225, r=luqmana

Add regression tests for error message when using enum variant as a type

I'm guessing these were actually fixed with PR #27085.

Closes #21225
Closes #19197

Rollup merge of #33611 - vvanders:master, r=steveklabnik

Add a note about Higher-Ranked Trait Bounds in docs on Closures.

I hit a snag with lifetimes a few days ago and it wasn't until @birkenfeld pointed out Higher-Ranked Trait Bounds that I was able to solve the issue involving lifetimes on closure traits. This adds a small section in the book so that other users can find it.

r? @steveklabnik

Rollup merge of #33353 - timothy-mcroy:E0502, r=sanxiyn

Add error explanation for E0502

I am questioning the order of presentation on the suggested code fixes, but I'm not sure what would be best.  Thoughts?

r? @GuillaumeGomez

Auto merge of #33702 - crimsun:pr33678, r=alexcrichton

Resolved rustdoc crash (#33678) by aborting instead of unwrapping.

Also removed Option use and comment to match.

Fixes https://github.com/rust-lang/rust/issues/33678

Add new error code tests

Make the #[stable(since)] version attribute clearer with a tooltip

Reword the short diagnostic for E0509

Saying that a type *implements* a trait is much more idiomatic than saying it *defines* the trait.

Auto merge of #33694 - arielb1:fuzzy-on-unimplemented, r=nikomatsakis

implement fuzzy matching in on_unimplemented

Fixes #31062

r? @nikomatsakis

[MIR] Add PointerCast for Unsize casts of fat pointers.

Auto merge of #33688 - jonathandturner:fix_old_school, r=nikomatsakis

Fix for old school error issues, improvements to new school

This PR:
* Fixes some old school error issues, specifically #33559, #33543, #33366
* Improves wording borrowck errors with match patterns
* De-emphasize multi-line spans, so we don't color the single source character when we're trying to say "span starts here"
* Rollup of #33392 (which should help fix #33390)

r? @nikomatsakis

Fix macro expansion backtrace diagnostics

rustbuild: Pass -O to tests based on configuration

Currently rustbuild isn't detecting the `-O` flag for tests via the
`--disable-optimize-tests` or not command line flag to `./configure`, and this
commit patches up the support to pass `-O` by default.

rustbuild: Add missing test suites

After a comparison with the current set of tests run it was discovered that
rustbuild accidentally wasn't running a few test suites. This commit adds back a
few more test suites:

* rfail-full
* pretty-rpass
* pretty-rpass-full
* pretty-rpass-valgrind
* pretty-rfail
* pretty-rfail-full
* librustc_bitflags unit tests

Auto merge of #33686 - GuillaumeGomez:error-code-tests, r=steveklabnik

Add new error code tests

r? @steveklabnik

address review comments

Move read more link to same line

Simplify report_elision_failure a little bit.

Rust syntax coloring for some ignore, should-panic and no-run snippets.

Clarified that `let(mut x, y) =` only makes x mutable, not y

rustdoc: Support short doc fallback for non-default items

rustdoc: Add doc snippets for trait impls, with a read more link

Fixes #33672

implement fuzzy matching in on_unimplemented

Auto merge of #33476 - nikomatsakis:incr-comp-xcrate, r=mw

track incr. comp. dependencies across crates

This PR refactors the compiler's incremental compilation hashing so that it can track dependencies across crates. The main bits are:

- computing a hash representing the metadata for an item we are emitting
  - we do this by making `MetaData(X)` be the current task while computing metadata for an item
  - this naturally registers reads from any tables and things that we read for that purpose
  - we can then hash all the inputs to those tables
- tracking when we access metadata
  - we do this by registering a read of `MetaData(X)` for each foreign item `X` whose metadata we read
- hashing metadata from foreign items
  - we do this by loading up metadata from a file in the incr. comp. directory
  - if there is no file, we use the SVH for the entire crate

There is one very simple test only at this point. The next PR will be focused on expanding out the tests.

Note that this is based on top of https://github.com/rust-lang/rust/pull/33228

r? @michaelwoerister

Be smart about span of parenthesized expression in macro

add task for linking

In MSVC (at least), linking requires accessing metadata, which generates
reads.

fix indentation of session/mod.rs

add debug info to dep_graph

nit: cache crate-hash for next time

nit: use format! instead of iterator

basic tests for cross-crate hashing

load/save hashes of metadata

This commit reorganizes how the persist code treats hashing. The idea is
that each crate saves a file containing hashes representing the metadata
for each item X. When we see a read from `MetaData(X)`, we can load this
hash up (if we don't find a file for that crate, we just use the SVH for
the entire crate).

To compute the hash for `MetaData(Y)`, where Y is some local item, we
examine all the predecessors of the `MetaData(Y)` node and hash their
hashes together.

allow retracing paths across crates

For external crates, we must build up a map that goes from
the DefKey to the DefIndex. We do this by iterating over each
index that is found in the metadata and loading the associated
DefKey.

cleanup dep-graph debugging code

Create some re-usable filtering subroutines.

change svh to store a u64

We used to store a u64 converted to a String for some reason. Now we
don't.

pass revision and incr_comp directory to auxbuild

This is needed for incremental compilation harness to support
cross-crate testing. Also support cfg for typechecking prettyprint

always encode variant fields

we need them to be able to retrace.

make the filename computation take a cratenum