`Span` has undergone some changes over the years (addition of an optional
parent, and possible inlining of the context in interned spans) but the
comments and identifiers used haven't kept up. As a result, I find it
harder to understand than I should.
This commit reworks the comments, renames some identifiers, and
restructures the code slightly, all to make things clearer. I now feel
like I understand this code again.
- It's used exactly once, so it's trivial to replace
- It doesn't match the normal convention for containers: normally
`get()` returns and option and indexing panics. Instead `get()` panicked
and there's no indexing operation available.
Various changes to the `rustc_span` docs, including the following:
- Additions to top-level docs
- Edits to the source_map module docs
- Edits to documentation for `Span` and `SpanData`
- Added intra-docs links
- Documentation for Levenshtein distances
- Fixed missing punctuation
