Documentation curation - FoundationEssentials

[invalidname]

Builds out the .docc catalog with curation for all types in FoundationEssentials, to provide a browsable version of the documentation.

Tip: Reviewers may find it easier to review the browsable preview rather than combing through the raw .md files directly.

Motivation:

This is the first step to hosting swift-foundation documentation on docs.swift.org, much the same way the Swift Standard Library documentation is now hosted there.

@parkera migrated much of the developer.apple.com documentation for Foundation to source files in #1917. However, if you build documentation today, all the top-level symbols would simply appear in a long list of "Classes", "Protocols", etc., without semantic organization.

This PR adds curation to the .docc catalog, which organizes all the symbols into topics, which makes the docs browsable. You can learn more about DocC curation in Adding Structure to Your Documentation Pages.

Modifications:

This PR adds several hundred .md files to FoundationEssentials.docc to provide the curation. It also corrects mistakes in the source doc comments copied over from Apple's Foundation, mostly to fix links that don't resolve, which is often due to the partitioning of swift-foundation into separate modules for FoundationEssentials and FoundationInternationalization.

Result:

Building out the curation in the .docc catalog allows you to drill down by topic: look in "Strings and Text" for AttributedString or "Dates and Times" for Calendar.

You can browse a preview of documentation built from this branch here.

Also, this PR curates the extensions that FoundationEssentials makes to types in the Standard Library, such as adding filter(_:) and sort(_:) methods to Sequence that take a Foundation Predicate and Comparator, respectively. Since the docs-building process for the Standard Library knows nothing about the extensions that swift-foundation makes to stdlib, this is the only place we can document those extensions (short of some completely out-of-band solution, like writing pages by hand).

This PR is mostly limited to FoundationEssentials. A later PR will curate FoundationInternationalization. When both are merged into a release branch, we'll be able to host these docs on swift.org.

Some symbols lack documentation; adding DocC comments to those symbols can happen in subsequent PRs, and we appreciate any contributions.

Testing:

Does not require testing. The only changes are to documentation comments in source and Markdown curation files in the .docc catalog.

[parkera]

Suggested change

	/// attributedString.link = URL(string:"https://example.com")
	/// attributedString.link = URL(string: "https://example.com")

Note, though, that this initializer has an optional result. Not sure how you want to handle it here.

[invalidname]

Ow. Good point. I want to replace the UIKit/SwiftUI attribute from the previous docs with something that exists within FoundationAttributes and is interesting, but you're right that all three of these snippets (all the way back to line 40) need to deal with the optional from URL(string:).

[invalidname]

Update: I still need to address this. I think it's reasonable to just force-unwrap in this case, since we can visually inspect the string and verify that it will parse correctly.