These are currently documented at
https://rustc-dev-guide.rust-lang.org/rustdoc-internals.html#hot-potato
but can easily go out of date. We'd like to document them in place and
link to
https://doc.rust-lang.org/nightly/nightly-rustc/rustdoc/passes/index.html

Many of `DocFolder`'s impls didn't actually transform the syntax tree,
so they can be visitors instead.

Previously it would unconditionally use edition 2015, which was
incorrect.

Previously, only the raw string and the `is_ignore` field were
preserved, which made it hard to recover anything else.

Use more accurate suggestion spans for

* argument parse error
* fully qualified path
* missing code block type
* numeric casts
* E0212

- Simplify boolean expression
- Give an example of invalid syntax
- Remove explanation of why code block is text

This also gives a better error message when a span is missing.

This adds a new lint to `rustc` that is used in rustdoc when a code
block is empty or cannot be parsed as valid Rust code.

Previously this was unconditionally a warning. As such some
documentation comments were (unknowingly) abusing this to pass despite
the `-Dwarnings` used when compiling `rustc`, this should not be the
case anymore.

Otherwise you get a lot of instances of `item.span.span()`, which is
just plain confusing. `item.span.inner()` conveys the correct meaning of
"get the type that `clean::Span` wraps".

Its type is called `clean::Span`, and also the name in the rest of
rustdoc and rustc for this kind of field is `span`.

This is needed for the next commit, which needs access to the `cx` from
within the `decorate` closure.

- Change `as_local_hir_id` to an associated function, since it only
  needs a `TyCtxt`
- Change `source_span_for_markdown_range` to only take a `TyCtxt`

This should hopefully allow for less interior mutability.

This gets rid of a bunch of `unwrap()`s and makes it a little more clear
what's going on.

Originally I wanted to make `fold_item` non-nullable too, which would
have been a lot nicer to work with, but unfortunately `stripper` does
actually return `None` in some places. I might make a follow-up moving
stripper to be special and not a pass so that passes can be
non-nullable.

This gives warnings about dead code.

`parse_stream_from_source_str` is a more stable API to convert a
string into a bunch of tokens, and it also catches errors about
mismatched parenthesis.

2. invert rustc_session & syntax deps
3. drop rustc_session dep in rustc_hir

For some errors the lexer will unwind so we need to handle that in addition to handling `token::Unknown`.

I believe rustdoc should not be conflating private items (visibility
lower than `pub`) and hidden items (attribute `doc(hidden)`). This
matters now that Cargo is passing --document-private-items by default
for bin crates. In bin crates that rely on macros, intentionally hidden
implementation details of the macros can overwhelm the actual useful
internal API that one would want to document.

This PR restores the strip-hidden pass when documenting private items,
and introduces a separate unstable --document-hidden-items option to
skip the strip-hidden pass. The two options are orthogonal to one
another.

The previous commit removes the use of this, and now we cleanup.

also move MACRO_ARGUMENTS -> librustc_parse