[Diagnostics] Introduce "Educational Notes" for diagnostics

[owenv]

Educational notes are small pieces of documentation which explain a concept
relevant to some diagnostic message. If -enable-descriptive-diagnostics is
passed, they will be printed after a diagnostic message if available.

Educational notes can be found at /usr/share/doc/diagnostics in a
toolchain, and are associated with specific compiler diagnostics in
EducationalNotes.def.

This is my first pass at implementing the feature as described here. The terminal UX has plenty of room for improvement, but this is gated behind -Xfrontend -enable-descriptive-diagnostics so that shouldn't be an issue for now. As a proof of concept I added a note explaining the difference between nominal and non-nominal types inspired by the many related questions on Stack Overflow and Brent's excellent answer here. Once this lands I plan on putting together some style guidelines before adding any more.

A couple of notes on the approach I took here:

• The documentation content is installed in a subdirectory of usr/share/doc in the toolchain. I picked this because it seemed to match Unix conventions and there didn't seem to be an existing location for this kind of content
• I chose to associate educational notes with diags in EducationalNotes.def instead of the existing Diagnostics*.def files for now. This avoids some nasty macro usage and preserves git history better. I'm starting to think about migrating diagnostic definitions to TableGen at some point though, they're becoming difficult to maintain...

[owenv]

@swift-ci please test

[owenv]

Hi @shahmishal , I recently got commit access but don't seem to be able to trigger the CI yet. Do you mind taking a look when you have a chance?

[hamishknight]

@swift-ci please test

[shahmishal]

Hi @shahmishal , I recently got commit access but don't seem to be able to trigger the CI yet. Do you mind taking a look when you have a chance?

Looking into this

[beccadax]

Good start, but let's think about some things at the outset.

[owenv]

I added a high level overview of the feature to Diagnostics.md which includes some basic guidelines for writing these notes, with the caveat that everything is still experimental and subject to change.

[beccadax]

@swift-ci please test

[beccadax]

Found a tiny grammar error, but I'm sure you'll fix that. Otherwise, looks like a good start.

[swift-ci]

Build failed
Swift Test Linux Platform
Git Sha - cccfe67a697d4a335ba3e44cf5c0c6088582f2e1

[DougGregor]

This is really cool, thank you for pushing it forward!

[owenv]

@swift-ci please smoke test

[owenv]

Hi @shahmishal , I recently got commit access but don't seem to be able to trigger the CI yet. Do you mind taking a look when you have a chance?

Looking into this

@shahmishal sorry to ping again, but were you able to figure out this issue?

[theblixguy]

@swift-ci please smoke test

[compnerd]

This seems to have broken the build on Windows: https://dev.azure.com/compnerd/windows-swift/_build/results?buildId=13763&view=logs&j=b9e62f99-1a98-5ed7-01d2-f4794231ed79&t=9d1c7fdf-e7ea-5e83-bbfd-5e0708569c31&l=4917

[owenv]

@compnerd #28170 is tracking a potential fix but is running into some Clang/MSVC compatibility issues. I have #28176 open to revert which might be best at this point.