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)

[heckj]

@ktoso if you're good with this, I'll need you to merge - I don't have commit access to override the semver issue that hiding the symbols caused.

[ktoso]

The API breaks are not real:

  💔 API breakage: var Counter._handler is now with @_documentation
  💔 API breakage: var Counter._factory is now with @_documentation
  💔 API breakage: var FloatingPointCounter._handler is now with @_documentation
  💔 API breakage: var FloatingPointCounter._factory is now with @_documentation
  💔 API breakage: var Meter._handler is now with @_documentation
  💔 API breakage: var Meter._factory is now with @_documentation
  💔 API breakage: var Recorder._handler is now with @_documentation
  💔 API breakage: var Recorder._factory is now with @_documentation
  💔 API breakage: var Timer._handler is now with @_documentation
  💔 API breakage: var Timer._factory is now with @_documentation

merging, thank you!