Available directive docs

[d-ronnqvist]

Bug/issue #, if applicable: rdar://131987745

Summary

This PR updates the documentation for the @Available directive to:

• lead with information about when to use it and when to use in-source annotation instead
• add documentation for the new "deprecated" parameter and mention which versions of DocC support it.
• rephrases several sentences to avoid passive voice, for preferring "when you introduced this API" over "when this API was introduced".
• Combine the 3 code examples into 1 and wraps it in a @Metadata directive so that it's clearer that @Available is used within @Metadata.

It also unhides and documents the @DeprecationSummary directive to:

• provide information about when to use @DeprecationSummary and when to use in-source annotation instead
• provide tips about using @DeprecationSummary and @Available together to give the reader the most information about a deprecated API.

Dependencies

None

Testing

Run swift run docc preview Sources/docc/DocCDocumentation.docc and preview:

• http://localhost:8080/documentation/docc/available
• http://localhost:8080/documentation/docc/deprecationsummary

Checklist

Make sure you check off the following items. If they cannot be completed, provide a reason.

• [ ] Added tests Not applicable
• Ran the ./bin/test script and it succeeded
• Updated documentation if necessary

[anferbui]

LGTM!

This is very good to know, I didn't know we had to regenerate Sources/docc/DocCDocumentation.docc/DocC.symbols.json to update Swift-DocC's symbol documentation. Will keep that in mind for future PRs!

[d-ronnqvist]

@swift-ci please test

[d-ronnqvist]

This is very good to know, I didn't know we had to regenerate Sources/docc/DocCDocumentation.docc/DocC.symbols.json to update Swift-DocC's symbol documentation.

Specifically for changes to directive documentation we need to know this.

[d-ronnqvist]

@swift-ci please test Linux

[d-ronnqvist]

@swift-ci please test

[d-ronnqvist]

@swift-ci please test