doc updates - formatting, organization, and language

[heckj]

• added explicit curation for the major types
• explicitly hides some of the types that aren't meant to be public
• revised the language to writing guidelines
  • removed symbols in abstracts
  • spelled out symbols in abstracts
• revised titles to single sentences
• updated grammar to switch to present tense

(the @_documentation updates reflect as breaking API changes, even though the availability of the symbols themselves aren't changed)

[heckj]

Checking the sound-ness manually:

swift package add-dependency https://github.com/swiftlang/swift-docc-plugin --from 1.0.0
swift package plugin generate-documentation --target "Metrics" --warnings-as-errors --analyze
swift package plugin generate-documentation --target "CoreMetrics" --warnings-as-errors --analyze
swift package plugin generate-documentation --target "MetricsTestKit" --warnings-as-errors --analyze

On Swift 6.2, all are passing without issue, but something is crashing in the GitHub workflow test pipeline for docs soundness.
The same works fine for checking against Swift 6.1, but the fails on Swift 6.0, which uses different(now legacy) disambiguation patterns for symbols and doesn't understand 6.1 and newer disambiguations.

[ktoso]

Thanks Joe! The api breakage isn’t real because it’s about underscored symbols and we’re just hiding them from docs.

[ktoso]

Looks good! Just some minor notes

[heckj]

I didn't add in the docs for the no-op handler, which depresses the coverage numbers a smidge, but most of the rest are in good shape in terms of just broad coverage and consistency:

                | Abstract        | Curated         | Code Listing
Types           | 100% (16/16)    | 100% (16/16)    | 38% (6/16)
Members         | 82% (113/137)   | 93% (127/137)   | 0.0% (0/137)
Globals         | 50% (1/2)       | 100% (2/2)      | 50% (1/2)