Rollup merge of #39166 - glandium:master, r=brson

Update jemalloc to include various fixes for OSX 10.12

Rollup merge of #39157 - michaelwoerister:debug-lto, r=alexcrichton

Add regression test for debuginfo + LTO

Fixes #25270, which cannot be reproduced with the current nightly version of the compiler anymore (due to various fixes to debuginfo generation in the past).

Should we run into the "possible ODR violation" again, the test added by this PR can be extend with the new case.

r? @alexcrichton

Rollup merge of #39146 - alexcrichton:fix-osx-debug, r=michaelwoerister

travis: Fix post-failure lldb invocation

Pass an absolute path, not just the basename.

Rollup merge of #39143 - nikomatsakis:issue-38967, r=eddyb

check inherent impls of traits for overlap as well

Simple oversight. Fixes #38967.

r? @eddyb

Rollup merge of #39142 - nikomatsakis:issue-38973, r=brson

run rustdoc tests in the same sort of thread rustc runs in

Not sure yet if this is the problem in #38973 but seems like an improvement regardless.

r? @brson

Rollup merge of #39138 - gralpli:issue-39089, r=nrc

Fix ICE when compiling fn f<T: ?for<'a> Sized>() {}

Fixes issue #39089

Rollup merge of #39135 - TheCycoONE:vec_drain_doc, r=alexcrichton

Clarify when range is removed by drain

Based on a discussion on #rust-beginners the existing note for drain is confusing. This new wording was suggested.

Rollup merge of #39132 - alexcrichton:static-libstdcpp, r=japaric

travis: Pass --enable-llvm-static-stdcpp

All our releases are compiled with this, so let's be sure to do so whenever
`DEPLOY` is set. This'll ensure that we don't have dynamic dependencies on
libstdc++ which LLVM depends on, but instead we link it all statically to have
more portable binaries.

Rollup merge of #39120 - alexcrichton:emscripten-tests, r=brson

travis: Get an emscripten builder online

This commit adds a new entry to the Travis matrix which will execute emscripten
test suites. Along the way it updates a few bits of the test suite to continue
passing on emscripten, such as:

* Ignoring i128/u128 tests as they're presumably just not working (didn't
  investigate as to why)
* Disabling a few process tests (not working on emscripten)
* Ignore some num tests in libstd (#39119)
* Fix some warnings when compiling

Rollup merge of #39118 - jseyfried:token_tree_based_parser, r=nrc

Refactor the parser to consume token trees

This is groundwork for efficiently parsing attribute proc macro invocations, bang macro invocations, and `TokenStream`-based attributes and fragment matchers.

This improves parsing performance by 8-15% and expansion performance by 0-5% on a sampling of the compiler's crates.

r? @nrc

Rollup merge of #39114 - alexcrichton:fix-osx-image, r=brson

travis: Tweak OSX image configuration

Somewhere between https://travis-ci.org/rust-lang/rust/jobs/192352185 and
https://travis-ci.org/rust-lang/rust/jobs/192440181 it looks like our
configuration for a newer OSX image was lost as LLDB has reverted itself back to
350. This fix appeared to work for the libc crate so let's see if we can
configure it to work for the rust repo as well.

Rollup merge of #39112 - alexcrichton:i586-msvc, r=nikomatsakis

appveyor: Test/Dist i586 MSVC

This is a target that we're shipping today, so this commit adds this matrix
entry to AppVeyor. This reuses the existing i686 MSVC matrix entry as it's
currently finishing about a half hour under two hours, which should hopefully
give it enough extra time to run this test suite.

cc #38531

Rollup merge of #39111 - alexcrichton:more-cross-targets, r=brson

travis: Expand the `cross` linux image

This expands the `cross` travis matrix entry with a few more targets that our
nightlies are building:

* x86_64-rumprun-netbsd
* arm-unknown-linux-musleabi
* arm-unknown-linux-musleabihf
* armv7-unknown-linux-musleabihf
* mips-unknown-linux-musl
* mipsel-unknown-linux-musl

This commit doesn't compile custom toolchains like our current cross-image does,
but instead compiles musl manually and then compiles libunwind manually (like
x86_64) for use for the ARM targets and just uses openwrt toolchains for the
mips targets.

cc #38531

Rollup merge of #39077 - jseyfried:crate_var_imports, r=nrc

Improve the warning cycle for `use $crate;`

Fixes #39049.
r? @nrc

Rollup merge of #39068 - alexcrichton:more-small-tests, r=brson

travis: Add i586 linux and i686 musl

This commit expands the existing x86_64-musl entry in the Travis matrix to also
build/test i586-unknown-linux-gnu and i686-unknown-linux-musl.

cc #38531
Closes #35599
Closes #39053

Rollup merge of #38966 - brson:relnotes, r=brson

1.15 release notes

[Rundered](https://github.com/brson/rust/blob/relnotes/RELEASES.md#version-1150-2017-02-02).

Lots of good stuff this release!

Perf graphs: https://goo.gl/KSVFvF, https://goo.gl/K98g8M, https://goo.gl/H1gSoz, https://goo.gl/yZBV2p, https://goo.gl/ltURbb. Not much change 😿

r? @steveklabnik

Rollup merge of #38842 - abonander:proc_macro_attribute, r=jseyfried

Implement `#[proc_macro_attribute]`

This implements `#[proc_macro_attribute]` as described in https://github.com/rust-lang/rfcs/pull/1566

The following major (hopefully non-breaking) changes are included:

* Refactor `proc_macro::TokenStream` to use `syntax::tokenstream::TokenStream`.
    * `proc_macro::tokenstream::TokenStream` no longer emits newlines between items, this can be trivially restored if desired
    * `proc_macro::TokenStream::from_str` does not try to parse an item anymore, moved to `impl MultiItemModifier for CustomDerive` with more informative error message

* Implement `#[proc_macro_attribute]`, which expects functions of the kind `fn(TokenStream, TokenStream) -> TokenStream`
    * Reactivated `#![feature(proc_macro)]` and gated `#[proc_macro_attribute]` under it
    * `#![feature(proc_macro)]` and `#![feature(custom_attribute)]` are mutually exclusive
    * adding `#![feature(proc_macro)]` makes the expansion pass assume that any attributes that are not built-in, or introduced by existing syntax extensions, are proc-macro attributes

* Fix `feature_gate::find_lang_feature_issue()` to not use `unwrap()`

    * This change wasn't necessary for this PR, but it helped debugging a problem where I was using the wrong feature string.

* Move "completed feature gate checking" pass to after "name resolution" pass

    * This was necessary for proper feature-gating of `#[proc_macro_attribute]` invocations when the `proc_macro` feature flag isn't set.

Prototype/Litmus Test: [Implementation](https://github.com/abonander/anterofit/blob/proc_macro/service-attr/src/lib.rs#L13) -- [Usage](https://github.com/abonander/anterofit/blob/proc_macro/service-attr/examples/post_service.rs#L35)

Rollup merge of #38761 - frewsxcv:thread-sleep-formatting, r=alexcrichton

Add 'platform-specific' section to `sleep_ms` to match `sleep`.

None

Auto merge of #39062 - martinhath:placement-in-binaryheap, r=nagisa

Implement placement-in protocol for `BinaryHeap`

Related to #30172, and loosley based on #38551.

At the moment, this PR is in a pretty rough state, but I wanted to get some feedback to see if I'm going in the right direction.

I hope the Mentor label of #30172 is still applicable, even though it's a year old 😄

Auto merge of #38955 - estebank:highlighted-diags, r=nikomatsakis

Teach Diagnostics to highlight text

Support styled `Diagnostic` output:

<img width="469" alt="mismatched types error with colorized types in the note" src="https://cloud.githubusercontent.com/assets/1606434/21871227/93a84198-d815-11e6-88b1-0ede3c7e28ef.png">

Closes #37532 and #38901.

r? @nikomatsakis CC @jonathandturner @nagisa @nrc

Auto merge of #38603 - arielb1:supertrait-self-3, r=nikomatsakis

traits with self-containing supertraits are not object safe

This should be the last time I fix this function.

Fixes #38404.

travis: Get an emscripten builder online

This commit adds a new entry to the Travis matrix which will execute emscripten
test suites. Along the way it updates a few bits of the test suite to continue
passing on emscripten, such as:

* Ignoring i128/u128 tests as they're presumably just not working (didn't
  investigate as to why)
* Disabling a few process tests (not working on emscripten)
* Ignore some num tests in libstd (#39119)
* Fix some warnings when compiling

Auto merge of #39136 - keeperofdakeys:proc-macro-doc-test, r=alexcrichton

Stop warning when doc testing proc macro crates

Fixes #39064

Add the test option to the session struct that is passed
to phase_2_configure_and_expand function inside the
rustdoc test module.

This prevents the warning code from triggering when
parsing proc_macro_derive attributes, just like when
`--test` is normally invoked.

This change makes the warning disappear, but I'm not sure what else it might change. So this early PR is mainly to run the test suite, and to get feedback.

Auto merge of #38465 - japaric:msp430-interrupt, r=eddyb

calling convention for MSP430 interrupts

This calling convention is used to define interrup handlers on MSP430 microcontrollers. Usage looks like this:

``` rust
#[no_mangle]
#[link_section = "__interrupt_vector_10"]
pub static TIM0_VECTOR: unsafe extern "msp430-interrupt" fn() = tim0;

unsafe extern "msp430-interrupt" fn tim0() {
  P1OUT.write(0x00);
}
```

which generates the following assembly:

``` asm
Disassembly of section __interrupt_vector_10:

0000fff2 <TIM0_VECTOR>:
    fff2:       10 c0           interrupt service routine at 0xc010

Disassembly of section .text:

0000c010 <_ZN3msp4tim017h3193b957fd6a4fd4E>:
    c010:       c2 43 21 00     mov.b   #0,     &0x0021 ;r3 As==00
    c014:       00 13           reti
        ...
```

Auto merge of #39180 - GuillaumeGomez:rollup, r=GuillaumeGomez

Rollup of 11 pull requests

- Successful merges: #38457, #38922, #38970, #39039, #39091, #39115, #39121, #39149, #39150, #39151, #39165
- Failed merges:

add cfail test for the new feature gate

Rollup merge of #39165 - frewsxcv:slice, r=GuillaumeGomez

A few improvements to the slice docs.

* Simplify `Option::iter_mut` doc example.
* Document 'empty' corner-cases for `slice::{starts_with, ends_with}`.
* Indicate 'true' as code-like.

Rollup merge of #39151 - canndrew:feature-gate-uninhabited-references, r=brson

Feature gate `&Void`'s uninhabitedness.

Here's a totally crazy PR which should never be merged.

Rollup merge of #39150 - birkenfeld:slice-doc, r=GuillaumeGomez

collections: update docs of slice get() and friends

Resubmit of #38216.

r? @GuillaumeGomez

BTW, instead of closing a PR just because it is old and the team member who offered to fix it up did not have the time to do so, why not ping them instead? (cc @alexcrichton)

Rollup merge of #39149 - circuitfox:E0122-type-def-trait-bounds-where-clause, r=arielb1

E0122 should apply with where clauses

Fixes #39122

Rollup merge of #39121 - grimreaper:eax/thethe, r=apasel422

minor typo fix

None

Rollup merge of #39115 - king6cong:master, r=nikomatsakis

consistent doc wording

Rollup merge of #39091 - richard-imaoka:E0491-long-explanation, r=GuillaumeGomez

Add error explanation for E0491

Refs #32777

Please let me know if any question or anything doesn't look right about this.

Rollup merge of #39039 - michaelwoerister:ignore-gdb-version, r=nrc

debuginfo: Ignore optimized enum tests for GDB versions that can't handle them.

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

r? @nrc
cc @Manishearth

Rollup merge of #38970 - apasel422:may-dangle, r=pnkfelix

Deprecate `#[unsafe_destructor_blind_to_params]`

CC #34761

r? @pnkfelix

Rollup merge of #38922 - chris-morgan:fs-markdown-link-fix, r=steveklabnik

Fix a couple of bad Markdown links

Rollup merge of #38457 - frewsxcv:include, r=GuillaumeGomez

Improvements to 'include' macro documentation.

None

Auto merge of #38464 - clarcharr:ip_cmp, r=sfackler

PartialEq and PartialOrd between IpAddr and Ipv[46]Addr.

PartialEq was rather useful, so, I figured that I'd implement it. I added PartialOrd for good measure.

calling convention for MSP430 interrupts

This calling convention is used to define interrup handlers on MSP430
microcontrollers. Usage looks like this:

``` rust
#[no_mangle]
#[link_section = "__interrupt_vector_10"]
pub static TIM0_VECTOR: unsafe extern "msp430-interrupt" fn() = tim0;

unsafe extern "msp430-interrupt" fn tim0() {
  P1OUT.write(0x00);
}
```

which generates the following assembly:

``` asm
Disassembly of section __interrupt_vector_10:

0000fff2 <TIM0_VECTOR>:
    fff2:       10 c0           interrupt service routine at 0xc010

Disassembly of section .text:

0000c010 <_ZN3msp4tim017h3193b957fd6a4fd4E>:
    c010:       c2 43 21 00     mov.b   #0,     &0x0021 ;r3 As==00
    c014:       00 13           reti
        ...
```

Auto merge of #38712 - clarcharr:duration_sum, r=sfackler

Sum for Duration

Implemented the `Sum` trait for `Duration`. Seems reasonable.

A few improvements to the slice docs.

* Simplify `Option::iter_mut` doc example.
* Document 'empty' corner-cases for `slice::{starts_with, ends_with}`.
* Indicate 'true' as code-like.

Update jemalloc to include various fixes for OSX 10.12

Add doctest to the proc-macro derive-test

Stop warning when doc testing proc macro crates

Add the actually_rustdoc option to the session that
is passed  to phase_2_configure_and_expand function
inside the rustdoc test module.

This prevents the warning code from triggering when
parsing proc_macro_derive attributes, just like when
`--test` is normally invoked.

Add regression test for debuginfo + LTO

Feature gate `&Void`'s uninhabitedness.

References to empty types are only considered empty if feature(never_type) is
enabled.

collections: update docs of slice get() and friends

for the new SliceIndex trait.  Also made the docs of the unchecked
versions a bit clearer; they return a reference, not an "unsafe
pointer".

E0122 should apply with where clauses

Auto merge of #38168 - estebank:help-E0034, r=nrc

E0034: provide disambiguated syntax for candidates

For a given file

```rust
trait A { fn foo(&self) {} }
trait B : A { fn foo(&self) {} }

fn bar<T: B>(a: &T) {
  a.foo()
}
```

provide the following output

```
error[E0034]: multiple applicable items in scope
 --> file.rs:6:5
  |
6 |   a.foo(1)
  |     ^^^ multiple `foo` found
  |
note: candidate #1 is defined in the trait `A`
 --> file.rs:2:11
  |
2 | trait A { fn foo(&self, a: usize) {} }
  |           ^^^^^^^^^^^^^^^^^^^^^^^^^^
help: to use it here write `A::foo(&a, 1)` instead
 --> file.rs:6:5
  |
6 |   a.foo(1)
  |     ^^^
note: candidate #2 is defined in the trait `B`
 --> file.rs:3:15
  |
3 | trait B : A { fn foo(&self, a: usize) {} }
  |               ^^^^^^^^^^^^^^^^^^^^^^^^^^
help: to use it here write `B::foo(&a, 1)` instead
 --> file.rs:6:5
  |
6 |   a.foo(1)
  |     ^^^
```

Fix #37767.

travis: Fix post-failure lldb invocation

Pass an absolute path, not just the basename.

Auto merge of #39019 - nikomatsakis:issue-38919, r=eddyb

only consider value items when searching for methods, not types

Fixes #38919

r? @eddyb

check inherent impls of traits for overlap as well

run rustdoc tests in the same sort of thread rustc runs in

tolerate `None` return from `get_line`

more complete error message

Teach Diagnostics to highlight text

1.15 release notes

Fix ICE when compiling fn f<T: ?for<'a> Sized>() {}

Auto merge of #37972 - bluss:iter-find-is-on-a-roll, r=sfackler

Improve the slice iterator's searching methods

Improve all, any, find, position, rposition by explicitly unrolling the loop for the slice iterators.

- Introduce a few extension methods and functions for raw pointers make the new code easy to express
- Introduce helper methods `search_while, rsearch_while` that generalize all the searching methods

LLVM doesn't unroll the loop in `.find()` by default (clang is the same), so performance benefits a lot from explicit unrolling here. An iterator method without conditional exits (like `.fold()`) does not need this on the other hand.

One of the raw pointer extension methods is `fn post_inc(&mut self) -> Self` which is the rustic equivalent of “`ptr++`”, and it is a nice way to express the raw pointer loop (see commit 3).

Specific development notes about `search_while`: I tried both computing an end pointer "rounded" to 4, as well as the `ptrdistance >= 4` loop condition, ptrdistance was better. I tried handling the last 0-3 elements unrolled or with a while loop, the loop was better.

Fix fallout in `rustdoc`.

Remove the lookahead buffer.

Clarify when range is removed by drain

Based on a discussion on #rust-beginners the existing note for drain is confusing. This new wording was suggested.

Fix BinaryHeap place by only constructing vec::PlaceBack once

Auto merge of #39109 - michaelwoerister:incr-comp-cache-cleanup, r=nikomatsakis

incr.comp.: Delete orphaned work-products.

The new partitioning scheme uncovered a hole in our incr. comp. cache directory garbage collection. So far, we relied on unneeded work products being deleted during the initial cache invalidation phase. However, we the new scheme, we get object files/work products that only contain code from upstream crates. Sometimes this code is not needed anymore (because all callers have been removed from the source) but because nothing that actually influences the contents of these work products had changed, we never deleted them from disk.

r? @nikomatsakis

travis: Pass --enable-llvm-static-stdcpp

All our releases are compiled with this, so let's be sure to do so whenever
`DEPLOY` is set. This'll ensure that we don't have dynamic dependencies on
libstdc++ which LLVM depends on, but instead we link it all statically to have
more portable binaries.

Auto merge of #39100 - Mark-Simulacrum:fix-stage1, r=eddyb

Fix stage 1 tests broken because i128 doesn't work in stage 1

Broken by https://github.com/rust-lang/rust/pull/38992.

Add error explanation for E0491

Auto merge of #39110 - petrochenkov:sum, r=eddyb

Merge ObjectSum and PolyTraitRef in AST/HIR + some other refactoring

`ObjectSum` and `PolyTraitRef` are the same thing (list of bounds), they exist separately only due to parser quirks. The second commit merges them.

The first commit replaces `Path` with `Ty` in (not yet supported) equality predicates. They are parsed as types anyway and arbitrary types can always be disguised as paths using aliases, so this doesn't add any new functionality.

The third commit uses `Vec` instead of `P<[T]>` in AST. AST is not immutable like HIR and `Vec`s are more convenient for it, unnecessary conversions are also avoided.

The last commit renames `parse_ty_sum` (which is used for parsing types in general) into `parse_ty`, and renames `parse_ty` (which is used restricted contexts where `+` is not permitted due to operator priorities or other reasons) into `parse_ty_no_plus`.

This is the first part of https://github.com/rust-lang/rust/issues/39085#issuecomment-272743755 and https://github.com/rust-lang/rust/issues/39080 focused on data changes and mechanical renaming, I'll submit a PR with parser changes a bit later.

r? @eddyb

Auto merge of #39095 - nagisa:fix-ub-in-testhelp, r=alexcrichton

Fix UB in test helpers

Macro expansion producing defined has undefined behavior in C/C++.

minor typo fix

Avoid interpolated token trees.

Clean up `ext::tt::transcribe`.

Refactor the parser to consume token trees.

Introduce `string_reader.parse_all_token_trees()`.

Give the `StringReader` a `sess: &ParseSess`.

Auto merge of #39050 - alexcrichton:travis-nightly, r=brson

travis: Pass --release-channel=nightly on deploy

This commit passes the `--release-channel=nightly` flag to all images which have
the `DEPLOY` flag set. This means that we'll name artifacts and the compiler
appropriately.

This reworks a bit how arguments are passed, but for now doesn't change what's
already being passed. Eventually we'll want to avoid enabling debug assertions
and llvm assertions for *all* releases, but I figure we can tackle that a little
bit more down the road.

Rename ObjectSum into TraitObject in AST/HIR

Move "completed feature gate checking" pass to after "name resolution" pass so proc-macro-attribute feature gate check can use resolve

Fix `feature_gate::find_lang_feature_issue()` to not use `unwrap()`

Implement `#[proc_macro_attribute]`

* Add support for `#[proc_macro]`

* Reactivate `proc_macro` feature and gate `#[proc_macro_attribute]` under it

* Have `#![feature(proc_macro)]` imply `#![feature(use_extern_macros)]`,
error on legacy import of proc macros via `#[macro_use]`

travis: Pass --release-channel=nightly on deploy

This commit passes the `--release-channel=nightly` flag to all images which have
the `DEPLOY` flag set. This means that we'll name artifacts and the compiler
appropriately.

This reworks a bit how arguments are passed, but for now doesn't change what's
already being passed. Eventually we'll want to avoid enabling debug assertions
and llvm assertions for *all* releases, but I figure we can tackle that a little
bit more down the road.

Auto merge of #39090 - solson:exprkind-array, r=eddyb

Rename ExprKind::Vec to Array in HIR and HAIR.

This is a clearer name since they represent `[a, b, c]` array literals.

r? @eddyb

consistent doc wording

Auto merge of #39087 - nrc:qquote-empty-delim, r=jseyfried

proc macros/qquote: Handle empty delimited tokens

r? @jseyfried

Remove field `tokens_consumed` of `Parser`.

travis: Expand the `cross` linux image

This expands the `cross` travis matrix entry with a few more targets that our
nightlies are building:

* x86_64-rumprun-netbsd
* arm-unknown-linux-musleabi
* arm-unknown-linux-musleabihf
* armv7-unknown-linux-musleabihf
* mips-unknown-linux-musl
* mipsel-unknown-linux-musl

This commit doesn't compile custom toolchains like our current cross-image does,
but instead compiles musl manually and then compiles libunwind manually (like
x86_64) for use for the ARM targets and just uses openwrt toolchains for the
mips targets.

travis: Tweak OSX image configuration

Somewhere between https://travis-ci.org/rust-lang/rust/jobs/192352185 and
https://travis-ci.org/rust-lang/rust/jobs/192440181 it looks like our
configuration for a newer OSX image was lost as LLDB has reverted itself back to
350. This fix appeared to work for the libc crate so let's see if we can
configure it to work for the rust repo as well.

appveyor: Test/Dist i586 MSVC

This is a target that we're shipping today, so this commit adds this matrix
entry to AppVeyor. This reuses the existing i686 MSVC matrix entry as it's
currently finishing about a half hour under two hours, which should hopefully
give it enough extra time to run this test suite.

Auto merge of #38949 - GuillaumeGomez:fix_linker, r=nagisa

Fix linker failure on windows

Fixes #38933.

r? @ollie27

ignore-gdb-version: Address review comments.

syntax: Rename parse_ty -> parse_ty_no_plus, parse_ty_sum -> parse_ty

Use resizable Vec instead of P<[T]> in AST

incr.comp.: Delete orphaned work-products.

AST/HIR: Merge ObjectSum and PolyTraitRef

Auto merge of #39108 - GuillaumeGomez:rollup, r=GuillaumeGomez

Rollup of 6 pull requests

- Successful merges: #38247, #39028, #39065, #39084, #39105, #39106
- Failed merges:

Rollup merge of #39106 - istankovic:patch-2, r=GuillaumeGomez

libcollections: btree/set: fix a typo

Rollup merge of #39105 - istankovic:patch-1, r=sfackler

libcollections: btree/map: fix typos

Rollup merge of #39084 - sphela:book-update-patterns, r=steveklabnik

An update to patterns documentation

As it is written the current pattern page creates a lot of confusion, even for someone with previous rust experience. It's so hard because it introduces an entirely new language feature without explaining. Someone could update it within the span of a few minutes by just explaining the newly introduced feature.

```rust
match c {
    x => println!("x: {} c: {}", x, c),
}
```
No where in the book up to this point has it explained that identifiers match patterns with just a name create an irrefutable pattern. The page uses this feature without explanation, it just assumes that readers would immediately understand it. To confuse the issue even further the topic uses this feature to explain shadowing, placing two x's from different scopes and different meanings without ever explaining why there is shadowing.

What follows comes across as utterly nonsensical given everything the reader would know about Rust about this point:

```rust
the result:
x: c c: c
x: x
```

x is c? What? Yes even if you understand that x here is not the x in the previous scope why would x equal 'c' here? What previous chapter explained this? The previous chapter on 'matching' only mentions the catch all '_' and never in any shape or form mentioned that a name here creates an irrefutable pattern and binds a value.

There are numerous examples of people not understanding this section, not finding answers and looking for them online about `x: c c: c`:

https://github.com/rust-lang/book/issues/316

https://stackoverflow.com/questions/35563141/match-shadowing-example-in-the-patterns-section-of-the-rust-book-is-very-perplex

https://users.rust-lang.org/t/confusion-about-match-and-patterns/3937

https://www.bountysource.com/issues/38852461-question-on-patterns-section-shadowing-example-existing-book

And a [google search for `rust x: c c: c`](https://www.google.com/search?q=rust+%22x:+c+c:+c%22) finds many more people being tripped up, including people who speak a language other than English. I am confident that this page has resulted in questions on the irc channel more than once. Given rust already has a pretty big learning curve I recommend this be fixed.

I was asked to create PR from where I made this same case in the [rust book repository issue](https://github.com/rust-lang/book/issues/316) (I didn't realize this was a separate project).

Rollup merge of #39065 - frewsxcv:libstd-os-unix-ffi-docs, r=GuillaumeGomez

Add doc examples & description in `std::os::unix::ffi`.

None

Rollup merge of #39028 - frewsxcv:libstd-env-docs, r=brson

Minor improvements to docs in std::env structures/functions.

* Call functions "functions" instead of "methods".
* Link structures to their constructor functions
* Add other misc. documentation links