Rollup of 10 pull requests

- Successful merges: #46938, #47193, #47508, #47510, #47532, #47535, #47559, #47568, #47573, #47578
- Failed merges:

remove bogus assertion and comments

The code (incorrectly) assumed that constants could not have generics
in scope, but it's not really a problem if they do.

Fixes #47153

r? @pnkfelix

Update BTreeMap recommendation

Focus on the ordering / range(instead of all) benefit as it's the most important feature.

Closure argument mismatch tweaks

 - use consistent phrasing for expected and found arguments
 - suggest changing arguments to tuple if possible
 - suggest changing single tuple argument to arguments if possible

Fix #44150.

Give TargetOptions::linker a sane default value for CloudABI.

Though some parts of rust use cc-rs to invoke a compiler/linker, Cargo
seems to make use of the TargetOptions::linker property. Make the out of
the box experience for CloudABI a bit better by using the same compiler
name as cc-rs.

Fix the "Github - About Pull Requests" link in CONTRIBUTING.md

Previously the text that is supposed to link to the Github Pull Requests page, instead linked to the same file (CONTRIBUTING.md).

add target/ to ignored tidy dirs

Sometimes you get a target directory from running cargo in the rust repo (the root is `src/`), and it contains generated files. Just whitelist it since it causes tidy to spew warnings uncontrollably.

Add some edge cases to the documentation of `Path`

Affected methods are `starts_with` and `strip_prefix`.

Deprecate std::net::lookup_host

We intended to do this quite a while ago but it snuck through.

r? @alexcrichton

add Rust By Example to the bookshelf

cc #46194

With #46196 freshly merged, we should add a link to the main docs distribution so people can find it! We discussed this at the docs team meeting today and decided to go ahead with adding it to the bookshelf.

Add transpose conversions for nested Option and Result

These impls are useful when working with combinator
methods that expect an option or a result, but you
have a `Result<Option<T>, E>` instead of an `Option<Result<T, E>>`
or vice versa.

add kbd style tag to main.css in rustdoc

Added css style for kbd tags so they actually look like keys.
Result preview and discussion was going on in #46900 .

Auto merge of #46980 - zackmdavis:and_the_case_of_the_needlessly_parenthesized_arguments, r=petrochenkov

in which the unused-parens lint comes to cover function and method args

Resolves #46137.

Rename std::ptr::Shared to NonNull and stabilize it

This implements the changes proposed at https://github.com/rust-lang/rust/issues/27730#issuecomment-352800629:

> * Rename `Shared<T>` to `NonNull<T>` and stabilize it. (Being in the `ptr` module is enough to say that it’s a pointer. I’m not very attached to this specific name though.)
> * Rename `Box<T>` methods ~~`from_unique`~~/`into_unique` to ~~`from_nonnull`~~/`into_nonnull` (or whatever names are deemed appropriate), replace `Unique<T>` with `NonNull<T>` in their signatures, and stabilize them.
> *  Replace `Unique<T>` with `NonNull<T>` in the signatures of methods of the `Alloc` trait.
> * Mark `Unique` “permanently-unstable” by replacing remaining occurrences of `#[unstable(feature = "unique", issue = "27730")]` with:
>
>   ```rust
>   #[unstable(feature = "ptr_internals", issue = "0", reason = "\
>       use NonNull instead and consider PhantomData<T> (if you also use #[may_dangle]), \
>       Send, and/or Sync")]
>   ```
>
>   (Maybe the `reason` string is only useful on the struct definition.) Ideally it would be made private to some crate instead, but it needs to be used in both liballoc and libstd.
> * (Leave `NonZero` and `Zeroable` unstable for now, and subject to future bikeshedding.)

https://github.com/rust-lang/rust/issues/47336

https://github.com/rust-lang/rust/pull/41064

Per https://github.com/rust-lang/rust/pull/46952#issuecomment-353956225

Thew `_raw` prefix is included because the fact that `Box`’s ownership
semantics are "dissolved" or recreated seem more important than the exact
parameter type or return type.

`Shared` is now a deprecated `type` alias.

CC https://github.com/rust-lang/rust/issues/27730#issuecomment-352800629

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

 - use consistent phrasing for expected and found arguments
 - suggest changing arugments to tuple if possible
 - suggest changing single tuple argument to arguments if possible

Speed up leb128 encoding and decoding for unsigned values.

Make the implementation for some leb128 functions potentially faster.

@Mark-Simulacrum, could you please trigger a perf.rlo run?

Focus on the ordering/range benefit.

avoid double-unsizing arrays in bytestring match lowering

The match lowering code, when lowering matches against bytestrings,
works by coercing both the scrutinee and the pattern to `&[u8]` and
then comparing them using `<[u8] as Eq>::eq`.

If the scrutinee is already of type `&[u8]`, then unsizing it is both
unneccessary and a trait error caught by the new and updated MIR typeck,
so this PR changes lowering to avoid doing that (match lowering tried to
avoid that before, but that attempt was quite broken).

Fixes #46920.

r? @EddyB

Though some parts of rust use cc-rs to invoke a compiler/linker, Cargo
seems to make use of the TargetOptions::linker property. Make the out of
the box experience for CloudABI a bit better by using the same compiler
name as cc-rs.

Update rustfmt to 0.3.6

r? @nrc

Don't include DefIndex in proc-macro registrar function symbol.

There can only ever be one registrar function per plugin or proc-macro crate, so adding the `DefIndex` to the function's symbol name does not serve a real purpose. Remove the `DefIndex` from the symbol name makes it stable across incremental compilation sessions.

This should fix issue #47292.

Compute LLVM argument indices correctly in face of padding

Closes #47278

r? @EddyB

Resolves #46137.