We've been converging the implementations of educational notes and
diagnostic groups, where both provide category information in
diagnostics (e.g., `[#StrictMemorySafety]`) and corresponding
short-form documentation files. The diagnostic group model is more
useful in a few ways:
* It provides warnings-as-errors control for warnings in the group
* It is easier to associate a diagnostic with a group with
GROUPED_ERROR/GROUPED_WARNING than it is to have a separate diagnostic
ID -> mapping.
* It is easier to see our progress on diagnostic-group coverage
* It provides an easy name to use for diagnostic purposes.
Collapse the educational-notes infrastructure into diagnostic groups,
migrating all of the existing educational notes into new groups.
Simplify the code paths that dealt with multiple educational notes to
have a single, possibly-missing "category documentation URL", which is
how we're treating this.
Implements several enhancements to DiagnosticEngine’s handling of Decl arguments:
• All Decl classes, not just ValueDecls, are now valid to use as arguments.
• There is built-in logic to handle accessors by printing a phrase like `getter for 'foo'`, so this no longer has to be special-cased for each diagnostic.
• `%kind` can be used to insert the descriptive kind before a name; `%kindonly` inserts only the descriptive kind. This can eliminate kind/name argument pairs.
• `%base` can insert only the base name, leaving out any argument labels; `%kindbase` combines `%kind` and `%base`.
This PR is marked NFC because there are no intentional uses of these changes yet.
We've made changes to the diagnostic verifier over time that we failed to actually document. Update docs/Diagnostics.md to describe:
* Fix-it alternation (cdcd726f92)
* Fix-it line offsets (2128678d56)
* Additional files (5036a55550)
* Ignoring `<unknown>` diagnostics (384ab780e9)
I've also slightly fleshed out the description of fix-it expectations.
* [Diagnostics] Turn educational notes on-by-default
* [Diagnostics] Only include educational notes in printed output if -print-educational-notes is passed
* Make -print-educational-notes a driver option
* [Diagnostics] Issue a printed remark if educational notes are available, but disabled
* [docs] Update educational notes documentation and add a contributing guide
* [Diagnostics] Cleanup PrintingDiagnosticConsumer handling of edu notes
* Revert "[Diagnostics] Issue a printed remark if educational notes are available, but disabled"
For now, don't notify users if edu notes are available but disabled. This decision can be reevaluated later.
A handful of people have recently asked me if such a thing existed;
now it does. There's certainly more that can be added here, but I
wanted to dump a bunch of the information in my brain into doc form.
