[Diagnostics] Reference markdown files for educational notes and diagnostic group documentation

[DougGregor]

Start including diagnostic category and category documentation in diagnostics. These are rendered by the updated diagnostic formatter as a reference like [#StrictMemorySafety]. That reference will be a link to the Markdown documentation in the toolchain:

t.swift:2:7: warning: expression uses unsafe constructs but is not marked with 'unsafe' [#StrictMemorySafety]
1 | func somethingUnsafe(x: Int) {
2 |   _ = UnsafeRawPointer(bitPattern: x)
  |       |- warning: expression uses unsafe constructs but is not marked with 'unsafe' [#StrictMemorySafety]
  |       |- note: reference to unsafe type 'UnsafeRawPointer'
  |       |- note: reference to initializer 'init(bitPattern:)' involves unsafe type 'UnsafeRawPointer'
  |       `- note: @unsafe conformance of 'UnsafeRawPointer' to protocol '_Pointer' involves unsafe code
3 | }
4 | 

[DougGregor]

@swift-ci please smoke test

[DougGregor]

I'm splitting the mechanical changes out into a separate PR at #79688 so we can fret over the UI experience in this PR. I think maybe I want to use # instead of ^ for the marker because ^ looks weird to me, and I'm not sure that rendering this information as part of the message text is actually the right call (vs. having the renderer do it).

[heckj]

FWIW - while the markdown for footnotes made sense to me when I first saw it, it's apparently not currently supported in swift-markdown (or any of the DocC chain above it), if that makes a difference.

Since the goal here looks to be a providing a link/refernce location over an arbitrary block of metadata, using a single # as a subsequent marker seems simpler, and is relatively easy to look for and parse (for an IDE tooling kind of use case)

[DougGregor]

FWIW - while the markdown for footnotes made sense to me when I first saw it, it's apparently not currently supported in swift-markdown (or any of the DocC chain above it), if that makes a difference.

Since the goal here looks to be a providing a link/refernce location over an arbitrary block of metadata, using a single # as a subsequent marker seems simpler, and is relatively easy to look for and parse (for an IDE tooling kind of use case)

It's another reason to go with #, which I just... tend to like more for entirely aesthetic reasons.

[DougGregor]

swiftlang/swift-syntax#2981

@swift-ci please smoke test

[DougGregor]

Merging this. There will be a follow-up to add the links at the end of the file.