extending the documentation content

[heckj]

• cleaning up grammar to use present tense and more direct phrasing
• extending documentation coverage

Current state:

                | Abstract        | Curated         | Code Listing
Types           | 71% (10/14)     | 64% (9/14)      | 0.0% (0/14)
Members         | 44% (49/111)    | 77% (85/111)    | 0.0% (0/111)
Globals         | 73% (8/11)      | 91% (10/11)     | 9.1% (1/11)

[czechboy0]

We could also enable the CI that checks all public APIs have docs, to avoid regressing in the future. We have it in other repos already, like openapi runtime.

• https://github.com/apple/swift-openapi-runtime/blob/7722cf8eac05c1f1b5b05895b04cfcc29576d9be/.swift-format#L19

[heckj]

Honestly, this one's on the lower more because there's a helper type that isn't strictly user facing, but conforms to a lot of protocol pieces (AsyncCancelOnGracefulShutdownSequence), and documenting all those internals doesn't actually add a tremendous amount of value, but I wanted to at least get the high level pieces done and add curation for the other types that are relevant.

I'm not convinced there's tremendous value in breaking above a given # in the docs coverage metrics, sufficient to add it to the CI checks. I'm happy that we've got the Docs soundness check more than anything else - the warnings are getting better about mismatched API and parameters as APIs evolve, etc - all of which has a lot more external value in my mind.