Duplication in reading and parsing documentation comments

[srawlins]

We scan and parse doc comments multiple times, and I think it would behoove us to make fewer passes. I believe that every single doc comment on public elements is:

1. scanned once for @nodoc and <nodoc>. We should drop support for the latter.
2. scanned once for \{@(template|tool|inject-html)\}. The regex here might be expensive. ~~This scan can be combined with 1.~~ (done in #2972)
3. scanned once for @canonicalFor (for libraries) or @(api|category|subCategory|image|samples (for other things).
4. parsed for comment references ([...]).
5. parsed by markdown, which begins with splitting on lines (markdown takes a List<String> lines). I think this happens separately from the parse in 4.
6. parsed for realsies for \{@(template|tool|inject-html)\}. This should probably also just take place as part of 2.

I believe we can also simplify things by only recognizing @nodoc, @template, @inject-html, @tool, and @category as the first non-whitespace text on a line. Maybe @nodoc must be the first or last line.

I dunno what the exit criteria is. This can be improved incrementally, and at some point, we'll decide that we've got diminishing returns or too much complexity, etc.