Rollup merge of #41007 - pgerber:dir_builder, r=frewsxcv

Improve documentation for `std::fs::DirBuilder`

Rollup merge of #40999 - irfanhudda:improve-option-docs, r=steveklabnik

Improve option API docs

Associated Issue: #29366

Improve `option` API docs for
* `IntoIter` struct
* `Iter` struct
* `IterMut` struct

r? @steveklabnik

Rollup merge of #40997 - donniebishop:from_utf8_linking, r=steveklabnik

Added links to types in from_utf8 description

References #29375. Link to types mentioned in the documentation for `from_utf8` (`str`, `&[u8`], etc). Paragraphs were reformatted to keep any one line from being excessively long, but are otherwise unchanged.

Rollup merge of #40992 - donniebishop:utf8err_linking, r=alexcrichton

Added links to from_utf8 methods in Utf8Error

Referencing  #29375. Linked the `from_utf8` methods for both `String` and `str` in the description. Also linked the `u8` to its documentation

Rollup merge of #40988 - eugene-bulkin:ascii-docs, r=frewsxcv

API Docs: ascii

Add/update docs for the `ascii` module per #29341.

r? @steveklabnik

Rollup merge of #40981 - Technius:master, r=steveklabnik

Add links and some examples to std::sync::mpsc docs

Addresses part of #29377
r? @steveklabnik

I took a stab at adding links to the `std::sync::mpsc` docs, and I also wrote a few examples.

Edit: Whoops, typed in `?r` instead of `r?`.

Rollup merge of #40977 - projektir:BarrierWaitResult_doc, r=steveklabnik

Updating the description for BarrierWaitResult #29377

Referencing `Barrier`, removing reference to `is_leader`.

Rollup merge of #40949 - stjepang:fix-vecdeque-docs, r=frewsxcv

Improve some docs for VecDeque

r? @GuillaumeGomez

Rollup merge of #40870 - alexcrichton:stabilize-windows-subsystem, r=aturon

rustc: Stabilize the `#![windows_subsystem]` attribute

This commit stabilizes the `#![windows_subsystem]` attribute which is a
conservative exposure of the `/SUBSYSTEM` linker flag on Widnows platforms. This
is useful for creating applications as well as console programs.

Closes #37499

Rollup merge of #40608 - GuillaumeGomez:mutex-doc-inconsistency, r=steveklabnik

Fix mutex's docs inconsistency

Fixes #40176.

r? @steveklabnik
cc @rust-lang/docs

Auto merge of #40811 - estebank:issue-32540, r=jonathandturner

Point at last valid token on failed `expect_one_of`

```rust
error: expected one of `.`, `;`, `?`, `}`, or an operator, found `)`
  --> $DIR/token-error-correct-3.rs:29:9
   |
25 |         foo()
   |              - expected one of `.`, `;`, `?`, `}`, or an operator after this
...
29 |     } else {
   |     ^ unexpected token
```

Fix #32540.

Auto merge of #41059 - TimNN:rollup, r=TimNN

Rollup of 1 pull requests

- Successful merges: #40998
- Failed merges: #41045

update image name for DEPLOY_ALT

Merge branch 'master' into issue-32540

fix rollup

Merge remote-tracking branch 'hub/centos5-vault' into rollup

Rollup merge of #40998 - alexcrichton:split-dist, r=TimNN

travis: Split all dist builders in two

Previously we would use one builder on Travis to produce two sets of host
compilers for two different targets. Unfortunately though we've recently
increased how much we're building for each target so this is starting to take
unnecessarily long (#40804). This commit splits the dist builders in two by
ensuring that we only dist one target on each builder, which should take a much
shorter amount of time. This should also unblock other work such as landing the
RLS (#40584).

Fix styling issues

use fixed ip for vault.centos.org until updates have propagated to all mirrors

switch to vault.centos.org

travis: Split all dist builders in two

Previously we would use one builder on Travis to produce two sets of host
compilers for two different targets. Unfortunately though we've recently
increased how much we're building for each target so this is starting to take
unnecessarily long (#40804). This commit splits the dist builders in two by
ensuring that we only dist one target on each builder, which should take a much
shorter amount of time. This should also unblock other work such as landing the
RLS (#40584).

Fix mutex's docs inconsistency

Auto merge of #40915 - nrc:save-assoc, r=eddyb

save-analysis: track associated types

r? @eddyb

Auto merge of #40919 - GuillaumeGomez:fix-new-rustdoc, r=frewsxcv,steveklabnik

Add support for image, rules and footnotes

Part of #40912.

r? @rust-lang/docs

PS: the footnotes are waiting for https://github.com/google/pulldown-cmark/pull/21 to be merged to be fully working.

Improve documentation for `std::fs::DirBuilder`

Minor changes to core::option docs

Improve docs of core::option::Iter

Improve docs of core::option::IterMut

Improve docs of core::option::IntoIter

Added links to types in from_utf8 description

rustc: Stabilize the `#![windows_subsystem]` attribute

This commit stabilizes the `#![windows_subsystem]` attribute which is a
conservative exposure of the `/SUBSYSTEM` linker flag on Widnows platforms. This
is useful for creating applications as well as console programs.

Closes #37499

Add more std::ascii module-level docs.

Clean up std::ascii sub-level docs.

* Change `utf8` variable names to `non_ascii` to be more clear, since
ASCII and UTF-8 are compatible.

* Fix `EscapeDefault` struct description to follow the typical iterator
method format with a link to the generating function.

* Add more `escape_default` examples to cover every case mentioned in
the function description itself.

Force footnote references to be sorted by id

Fix warnings in examples

Auto merge of #40967 - alexcrichton:old-osx, r=brson

travis: Compile OSX releases with Xcode 7

Unfortunately what we're using right now, Xcode 8.2, cannot compile LLVM for OSX
10.7. We've done this historically and Gecko would like to maintain this
compabitiliby. This commit moves our release builders for OSX to using Xcode 7
which can compile LLVM for 10.7.

The builders running tests continue to use Xcode 8.2, however, because the LLDB
version with Xcode 7, 350, is blacklisted in running our LLDB tests. To continue
running LLDB tests we'll stick with Xcode 8.2.

Added links to from_utf8 methods in Utf8Error

Fix broken links to std::iter::Iterator::next

Change wording for push_front

Add links and examples to std::sync::mpsc docs (#29377)

This change adds links to to `Receiver`, `Iter`, `TryIter`, `IntoIter`,
`Sender`, `SyncSender`, `SendError`, `RecvError`, `TryRecvError`,
`RecvTimeoutError`, `TrySendError`, `Sender::send`, `SyncSender::send`,
`SyncSender::try_send`, `Receiver::recv`, `Receiver::recv_timeout`,
`Receiver::iter`, and `Receiver::try_iter`.

Examples added to `Receiver`, `Sender`, `Receiver::iter`.

Auto merge of #40972 - frewsxcv:rollup, r=frewsxcv

Rollup of 6 pull requests

- Successful merges: #40703, #40728, #40763, #40871, #40935, #40947
- Failed merges:

Updating the description for BarrierWaitResult #29377

Rollup merge of #40947 - stjepang:test-sort-random-cmp, r=alexcrichton

Test sort algorithms using a random cmp function

This ensures that sorting using a broken comparison function doesn't panic nor fail in some other way (especially not segfault).

r? @alexcrichton

Rollup merge of #40935 - donniebishop:str_boilerplate_docs, r=steveklabnik

Modify str Structs descriptions

References #29375. Modified descriptions of multiple structs to be more in line with structs found under [`std::iter`](https://doc.rust-lang.org/std/iter/#structs), such as [`Chain`](https://doc.rust-lang.org/std/iter/struct.Chain.html) and [`Enumerate`](https://doc.rust-lang.org/std/iter/struct.Enumerate.html)

Rollup merge of #40871 - projektir:atomic_links, r=steveklabnik

Adding links for Atomics docs #29377

r? @steveklabnik

This should be good for `std::sync::atomic`. The other pages still need more (examples, etc.).

Rollup merge of #40763 - pirate:patch-2, r=steveklabnik

Add helpful hint in io docs about how ? is not allowed in main()

This is my effort to help alleviate the confusion caused by the error message:
```rust
error[E0277]: the trait bound `(): std::ops::Carrier` is not satisfied
  --> hello_world.rs:72:5
   |
72 |     io::stdin().read_line(&mut d_input)?;
   |     ------------------------------------
   |     |
   |     the trait `std::ops::Carrier` is not implemented for `()`
   |     in this macro invocation
   |
   = note: required by `std::ops::Carrier::from_error`

error: aborting due to previous error
```
This has been discussed at length in https://github.com/rust-lang/rust/issues/35946, but I figured it would be helpful to mention in the docs.
Reading user input is one of the first things beginners will look up in the docs, so my thinking was they'd see this warning here and not have to deal with the [tricky error message](https://blog.rust-lang.org/2017/03/02/lang-ergonomics.html).

If you think this isn't the right place to put this in the docs, that's understandable, I'm open to suggestions for putting it elsewhere or removing it entirely.

Rollup merge of #40728 - topecongiro:stabilize, r=arielb1

Make overlapping_inherent_impls lint a hard error

Closes #36889.

Rollup merge of #40703 - GuillaumeGomez:pointer-docs, r=steveklabnik

Add missing urls in ptr docs

r? @rust-lang/docs

travis: Compile OSX releases with Xcode 7

Unfortunately what we're using right now, Xcode 8.2, cannot compile LLVM for OSX
10.7. We've done this historically and Gecko would like to maintain this
compabitiliby. This commit moves our release builders for OSX to using Xcode 7
which can compile LLVM for 10.7.

The builders running tests continue to use Xcode 8.2, however, because the LLDB
version with Xcode 7, 350, is blacklisted in running our LLDB tests. To continue
running LLDB tests we'll stick with Xcode 8.2.

Add end whitespace ignore flag for tidy

Fix hard break issue

Auto merge of #40950 - frewsxcv:rollup, r=frewsxcv

Rollup of 10 pull requests

- Successful merges: #40694, #40842, #40869, #40888, #40898, #40904, #40925, #40928, #40929, #40934
- Failed merges:

Rollup merge of #40934 - SamWhited:improve_write_writeln_docs, r=steveklabnik

Improve the docs for the write and writeln macros

This change reduces duplication by linking the documentation for
`writeln!` to `write!`. It also restructures the `write!` documentation
to read in a more logical manner (I hope; feedback would be welcome).

Updates #29329, #29381

Rollup merge of #40929 - bluss:full-reverse, r=alexcrichton

Implement all PartialOrd methods for Reverse

When making a forwarding wrapper we must in general forward all methods,
so that we use the type's own `lt` for example instead of the default.

Example important case: f32's partial_cmp does several operations but
its lt is a primitive.

Follow up on #40720

Rollup merge of #40928 - GAJaloyan:patch-2, r=eddyb

adding debug in consume_body function

When in debug_assertions=true mode, the function consume_body lacks some debug output, which makes it harder to follow the control flow. This commit adds this needed debug.

Rollup merge of #40925 - DaseinPhaos:patch-5, r=steveklabnik

Add missing link in unstable-book

add link to specialization's tracking issue

Rollup merge of #40904 - rap2hpoutre:patch-1, r=steveklabnik

Add example to std::process::abort

This is a first step in order to complete this issue: https://github.com/rust-lang/rust/issues/29370
I submitted this PR with the help of @steveklabnik More info here: https://github.com/rust-lang/rust/issues/29370#issuecomment-290089330

It's my first PR on Rust, I'm learning how to contribute: Should I ping someone? I will post another PR with a more complicated example soon, I prefer send it separately (cause maybe I made some mistakes).

Rollup merge of #40898 - MaloJaffre:remove-unused-feature, r=alexcrichton

Remove unused feature from error index generator

Remove feature `rustdoc`.

Rollup merge of #40888 - wesleywiser:rustdoc_src_sidebar, r=GuillaumeGomez

Make the rustdoc sidebar white on `src` pages

Fixes #40724

Rollup merge of #40869 - ctjhoa:master, r=steveklabnik

Improve os::linux documentation (#29367)

Improve `os::linux` documentation according to #29367

r? @steveklabnik

Rollup merge of #40842 - Mic92:RawFd, r=aturon

Implement AsRawFd/IntoRawFd for RawFd

This is useful to build os abstraction like the nix crate does.
It allows to define functions, which accepts generic arguments
of data structures convertible to RawFd, including RawFd itself.
For example:

```
fn write<FD: AsRawFd>(fd: FD, buf: &[u8]) -> Result<usize>
write(file, buf);
```
instead of:
```
fn write(fd: RawFd, buf: &[u8]) -> Result<usize>
write(file.as_raw_fd(), buf);
```

cc @kamalmarhubi

Rollup merge of #40694 - frewsxcv:unstable-book-checker, r=steveklabnik

Sync all unstable features with Unstable Book; add tidy lint.

Add a tidy lint that checks for...

* Unstable Book sections with no corresponding SUMMARY.md links
* unstable features that don't have Unstable Book sections
* Unstable Book sections that don't have corresponding unstable features

Sync all unstable features with Unstable Book; add tidy lint.

Add a tidy lint that checks for...

* Unstable Book sections with no corresponding SUMMARY.md links
* unstable features that don't have Unstable Book sections
* Unstable Book sections that don't have corresponding unstable features

Improve some docs for VecDeque

Test sort algorithms using a random cmp function

Auto merge of #40737 - nagisa:safe-slicing-strs, r=BurntSushi

Checked slicing for strings

cc https://github.com/rust-lang/rust/issues/39932

Add links to std::sync::mpsc docs #29377

Auto merge of #40620 - laumann:slash-in-diagnostics-path, r=BurntSushi

Replace hardcoded forward slash with path::MAIN_SEPARATOR

Fixes #40149

Fix multiple footnotes and improve testing

Remove parentheses in method references

Revert SplitWhitespace's description

Original headline of SplitWhitespace's description is more descriptive as to what it contains and iterates over.

Modify SplitWhitespace's description

Modify EncodeUtf16's description

Modify Chars' description

Modify CharIndices' description

Improve the docs for the write and writeln macros

This change reduces duplication by linking the documentation for
`writeln!` to `write!`. It also restructures the `write!` documentation
to read in a more logical manner.

Updates #29329, #29381

Modify Bytes' description

Modify Lines' description

Auto merge of #40524 - alexcrichton:update-bootstrap, r=alexcrichton

rustbuild: Update bootstrap compiler

Now that we've also updated cargo's release process this commit also changes the
download location of Cargo from Cargos archives back to the static.r-l.o
archives. This should ensure that the Cargo download is the exact Cargo paired
with the rustc that we release.

cmp: Implement all PartialOrd methods for Reverse

When making a forwarding wrapper we must in general forward all methods,
so that we use the type's own `lt` for example instead of the default.

Example important case: f32's partial_cmp does several operations but
its lt is a primitive.

removing trailing whitespaces

adding debug in consume_body function

When in debug_assertions=true mode, the function consume_body lacks some debug output, which makes it harder to follow the control flow. This commit adds this needed debug.

Auto merge of #40224 - nikomatsakis:issue-39808, r=eddyb

change the strategy for diverging types

The new strategy is as follows. First, the `!` type is assigned
in two cases:

- a block with a diverging statement and no tail expression (e.g.,
  `{return;}`);
- any expression with the type `!` is considered diverging.

Second, we track when we are in a diverging state, and we permit a value
of any type to be coerced **into** `!` if the expression that produced
it is diverging. This means that `fn foo() -> ! { panic!(); 22 }`
type-checks, even though the block has a type of `usize`.

Finally, coercions **from** the `!` type to any other are always
permitted.

Fixes #39808.
Fixes #39984.

Add missing link in unstable-book

add link to specialization's tracking issue

remove comments that were tripping up pretty printer

fix error message for issue-10176.rs

update UI test

We no longer give suggestions; this is presumably related to the changes
I made in coercion. However, those suggestions appear to be wrong
anyhow!

kill the graphviz-flowgraph tests

They are so annoying to update, and haven't caught any bugs afaik.

document `diverges` more correctly

fix `X as !` behavior

add test illustrating current "coerce to `!`" behavior

have coercion supply back the target type

The `try_coerce` method coerces from a source to a target
type, possibly inserting adjustments. It should guarantee
that the post-adjustment type is a subtype of the target type
(or else that some side-constraint has been registered which will lead
to an error). However, it used to return the (possibly adjusted) source
as the type of the expression rather than the target. This led to
less good downstream errors.

To work around this, the code around blocks -- and particular tail
expressions in blocks -- had some special case manipulation. However,
since that code is now using the more general `CoerceMany` construct (to
account for breaks), it can no longer take advantage of that. This lead
to some regressions in compile-fail tests were errors were reported at
"less good" locations than before.

This change modifies coercions to return the target type when successful
rather the source type. This extends the behavior from blocks to all
coercions. Typically this has limited effect but on a few tests yielded
better errors results (and avoided regressions, of course).

This change also restores the hint about removing semicolons which went
missing (by giving 'force-unit' coercions a chance to add notes etc).

remove `Clone` from `FnCtxt`

rename `only_has_type_or_fresh_var` to `coercion_target_type`

fix handling of blocks with `CoerceMany`

coercion now depends on whether the expression diverges

Before I was checking this in `demand_coerce` but that's not really the
right place. The right place is to move that into the coercion routine
itself.

avoid allocating a vector when the coercion sites are known upfront

cherry-pick over the tests I wrote for the reachability code

For the most part, the current code performs similarly, although it
differs in some particulars. I'll be nice to have these tests for
judging future changes, as well.

pacify the mercilous tidy

add regression test for #39808

Fixes #39808