rustc: middle: lint: use more doc comments
rustc: middle: ty: use doc comments for the tcx
rustc: add a lint for large enum variants

It can be easy to accidentally bloat the size of an enum by making one variant
larger than the others. When this happens, it usually goes unnoticed. This
commit adds a lint that can warn when the largest variant in an enum is more
than 3 times larger than the second-largest variant. This requires a little
bit of rejiggering, because size information is only available in trans, but
lint levels are only available in the lint context.

It is allow by default because it's pretty noisy, and isn't really *that*
undesirable.

Closes #10362
rustc: abstract lint level exporting from EnumSizeVariance
Cleanup lifetime guide
Clean pointers guide
get over bold text madness, changes per PR, brought the "returning pointers" section back to pointers guide
Add AttrId to Attribute_
First sketch of lint pass

Enough attributes are marked to cleanly compile an empty library.
Port more stuff to mark used attributes
Whitelist doc attributes

This is a bit overly permissive but should be okay for now.
Get "make check" to work with unused-attribute

There's a fair number of attributes that have to be whitelisted since
they're either looked for by rustdoc, in trans, or as needed. These can
be cleaned up in the future.
Changes from feedback
fix mostly grammar per PR comments
auto merge of #14373 : sfackler/rust/unused-attr, r=huonw

The compiler now tracks which attributes were actually looked at during the compilation process and warns for those that were unused.

Some things of note:

* The tracking is done via thread locals, as it made the implementation more straightforward. Note that this shouldn't hamper any future parallelization as each task can have its own thread local state which can be merged for the lint pass. If there are serious objections to this, I can restructure things to explicitly pass the state around.
* There are a number of attributes that have to be special-cased and globally whitelisted. This happens for four reasons:
  * The `doc` and `automatically_derived` attributes are used by rustdoc, but not by the compiler.
  * The crate-level attributes `license`, `desc` and `comment` aren't currently used by anything.
  * Stability attributes as well as `must_use` are checked only when the tagged item is used, so we can't guarantee that the compiler's looked at them.
  * 12 attributes are used only in trans, which happens after the lint pass.

#14300 is adding infrastructure to track lint state through trans, which this lint should also be able to use to handle the last case. For the other attributes, the right solution would probably involve a specific pass to mark uses that occur in the correct context. For example, a `doc` attribute attached to a match arm should generate a warning, but will not currently.

RFC: 0002-attribute-usage
Paper over privacy issues with Deref by changing field names.

Types that implement Deref can cause weird error messages due to their
private fields conflicting with a field of the type they deref to, e.g.,
previously

    struct Foo { x: int }

    let a: Arc<Foo> = ...;
    println!("{}", a.x);

would complain the the `x` field of `Arc` was private (since Arc has a
private field called `x`) rather than just ignoring it.

This patch doesn't fix that issue, but does mean one would have to write
`a._ptr` to hit the same error message, which seems far less
common. (This patch `_`-prefixes all private fields of
`Deref`-implementing types.)

cc #12808
auto merge of #14402 : huonw/rust/arc-field-rename, r=alexcrichton

Paper over privacy issues with Deref by changing field names.

Types that implement Deref can cause weird error messages due to their
private fields conflicting with a field of the type they deref to, e.g.,
previously

    struct Foo { x: int }

    let a: Arc<Foo> = ...;
    println!("{}", a.x);

would complain the the `x` field of `Arc` was private (since Arc has a
private field called `x`) rather than just ignoring it.

This patch doesn't fix that issue, but does mean one would have to write
`a._ptr` to hit the same error message, which seems far less
common. (This patch `_`-prefixes all private fields of
`Deref`-implementing types.)

cc #12808
core: rename strbuf::StrBuf to string::String

[breaking-change]
auto merge of #14323 : richo/rust/features/strbuf_to_string, r=huonw

Converts `StrBuf` to `String` throughout rustc and the standard library.

Tests all pass locally, but usual caveats about platforms that aren't OSX apply since I don't have a test environment handy.

@alexcritchon mentioned that @pcwalton may have a patch incoming that should block this?

closes #14312
Fix FIXME #5475 in std::ascii

Issue #5475 was closed some time ago, but ascii.rs still contained
a FIXME for it.
auto merge of #14415 : Sawyer47/rust/ascii-fixme, r=huonw

Issue #5475 was closed some time ago, but ascii.rs still contained
a FIXME for it.