Publishing stdlib documentation on swift.org

Development Standard Library
1

We’re happy to share that we’re working on bringing documentation for the Swift standard library to Swift.org.

Purpose and impact:

With this change, you’ll be able to browse documentation for the Swift standard library on Swift.org. Furthermore, you’ll be able to contribute to the documentation. The documentation for each symbol — protocols, methods, properties, and so on — come from triple-slash (///) comments above each symbol’s declaration in the source. When you use the DocC syntax in these comments, you can provide abstracts and discussions, code snippets, links to other symbols, and more. And since the doc comments are in code, maintaining the documentation follows the same process as any other code change: make changes in a pull request, incorporate any feedback on the PR, and merge the PR.

To learn more about authoring docs with DocC, see the DocC documentation.

Process:

To enable publishing the Swift standard library documentation, we’ve opened a pull request on the Swift language repository: #88061. This PR adds a DocC documentation catalog, which consists of a top-level .docc directory and a directory structure containing .md curation files. The curation files organize symbols into topics that make them easy to browse, by collecting related child symbols of a given type into topics. Curation also organizes free functions and other symbols not tied to a class, structure, or protocol into semantically-related API collections, making them easier to find.

We’ve also prepared a preview of the stdlib documentation, as generated from this branch.

Once this PR merges, the continuous integration system will be able to start building and publishing the standard library documentation. At first, the documentation will align with the current release, meaning the latest release/ branch. In the future, we hope to allow browsing the documentation for different releases, such as a preview of the next release.

–Chris
Developer Publications

33 Likes
2

I was waiting for the public announcement. Great to see progress here, thanks for doing the work! However, I do have a question. Could we add a Swift version to the availability list in addition to the usual Apple platforms?

5 Likes
3

This is a very good development! Not sure whether to post specific comments here or in the PR (neither seem perfectly apt):

Compare, for example, the following—

The docc preview points out that the (?)implementation and/or semantics of Int.negate are inherited from SignedNumeric, information that the official documentation doesn't surface. (Cool!)

But the documentation itself isn't "inherited" as it is in the official version. As it is, the API appears entirely undocumented when there's actually good info to be had. There are of course pros and cons to docc's approach which we don't need to hash out here, but is there any sort of quick-ish fix where at least that "Inherited from..." text can be a hyperlink to the relevant docs?

6 Likes
4

@NotTheNHK This is a good suggestion. I think it requires some support from the DocC team, so I’m going to take it as a feature request and file a radar. We know that some people are coming at this from the point of view of “toolchain version + Swift language” version and not “iOS version”, and we hope to improve things in that regard.

5

@xwu Thanks for the example. I’m not sure why negate() works differently here. If anything, I’m surprised that the developer.apple.com version picks up that discussion from SignedNumeric like that. I’ll look into it.

6

Thanks—to be clear, that’s just an easily reached example, but there’s nothing special about that specific API.

Apple’s documentation (and third-party tooling which followed that example before docc) has long worked that way in terms of “inheriting” documentation from protocols.

2 Likes
7

Speaking of BinaryInteger, why do the new docs list an init(asserting:) that's not mentioned in the Apple docs, and has no description?

1 Like
8

@xwu I re-ran the docc convert command with the flag --enable-inherited-docs, but it still doesn’t copy over the discussion from SignedInteger.negate(). I’ll take it up with the DevPubs docs team to see if they know why it works like that on developer.apple.com, but in the meantime, I don’t think it should block the PR, since it’s more likely a result of how we run the docc convert command and not the .docc catalog or its contents

2 Likes
9

@Nobody1707 So, it turns out that init(asserting:) is an extension on BinaryInteger that comes from the swift-experimental-string-processing sources, in Sources/_RegexParser/Utility/Misc.swift, lines 189-195 (as of today).

I could curate it into a topic like “Regex parser support”, or we could leave it as an uncurated symbol, with the expectation that as an “experimental” symbol, it may disappear in time.

This does bring up a longstanding question of whether symbols added by extensions should appear in the docs of the symbol being extended, or in the framework doing the extending. That’s beyond the scope of this PR, but it’s a legitimate question.

4 Likes