In August 2020, I posted a rant on the Swift forums about the poor state of Swift documentation. Nothing came of it, but I want to reiterate one point I made then: the Swift project sorely needs a searchable, linkable language reference.

To be fair, Swift does have a language reference: the eponymous section in The Swift Programming Language (TSPL) contains most of the information I’d expect from such a resource. But that section isn’t well structured to serve as an actual reference:

TSPL is not searchable

The TSPL website doesn’t have a search field. Even if it had one, I imagine it would be a full-text search over the entire site, as is common (and appropriate) for a book. A language reference needs a different search engine:

• Searching for keywords (if, case, where) must reliably find the documentation for the keyword as the top result. I don’t want to see the hundreds of pages that contain the word “if” in their body text.

• I’d love to be able to search for punctuation. Imagine if you could search for a symbol such as # and it would show you a list of all syntax elements that use this symbol.¹ This would be very informative and a great way to explore the language, not just for beginners — especially with good IDE integration (see below). Swift is such a big and complex language that most people won’t know every language feature.

A language reference needs a search engine that knows to handle keywords and punctuation.

TSPL is not linkable

Pages in TSPL tend to be long, with many separate items crammed into a single page. For example, all compiler attributes are documented on a single page.

Sharing a link to a specific attribute, such as @resultBuilder, is difficult if you know your way around HTML and pretty much impossible if you don’t (not to mention the bad URL).

As a reader, opening such a link is disorienting as it drops you in the middle of a very long page, 95 % of which is irrelevant to you.

The reader experience is even poorer when you arrive from a search engine (as most people would because the site has no search function): TSPL is one of the top results for swift resultbuilder on Google, but it drops you at the top of the superlong page on Attributes, with no indication where to find the information you’re looking for.

Every language construct, keyword, attribute, and compiler directive should have its own, linkable page.

TSPL is structured wrong

The Language Reference section in TSPL is organized as if it was written for parser or compiler developers. It uses the language’s grammar as a starting point and branches out into expressions, statements, declarations, and so on.

For example:

• try is listed under Expressions → Prefix Expressions → Try Operator.
• throw is under Statements → Control Transfer Statements → Throw Statement.
• throws is under Declarations → Function Declaration → Throwing Functions and Methods.

I don’t know about you, but as a user of the language, that’s not how I think about Swift or how I search for documentation.

In addition to a good search engine, a language reference needs an alphabetical index of every keyword or other syntax element, with links to the respective detail page.

IDE integration

I was careful to make this a complaint about the documentation for Swift and not about the (equally poor) state of Apple’s developer documentation. Swift is not limited to app development for Apple devices, and I believe it’s essential for Swift to position itself as a standalone project if it wants to be perceived as a viable general-purpose language.

It’s good that TSPL is hosted on swift.org and not developer.apple.com, and that’s also where this new language reference I’m envisioning should live. (I also think it’s wrong to host the Swift API documentation on developer.apple.com.)

But once we have this language reference, Apple should of course integrate it into Xcode for offline search and context-sensitive help. Imagine if you could Option-click not only identifiers but any token in a source file to see its documentation.

A few examples:

• Clicking on if case let would explain the pattern matching syntax.
• Clicking on in would explains the various closure expression syntax variants.
• Clicking on #fileID would show you an example of the resulting string and compare it to #file and filePath.
• Clicking on @propertyWrapper would explain what a property wrapper is and how you can implement one.
• Clicking on @dynamicMemberLookup would explain its purpose and what you have to do to implement it.
• Clicking on < in a generic declaration would explain what generic parameters are and how they are used.
• Clicking on ? would show all language elements that use a question mark (shorthand for Optionals, optional chaining, Optional pattern matching, try?).
• Clicking on /// would list the magic words Xcode understands in doc comments.

You get the idea. This would be such a big help, not only for beginners.

To summarize, this is the sad state of searching for language features in Xcode’s documentation viewer:

And this mockup shows how it could be: