Swift needs a better language reference – Ole Begemann

In August 2020, I posted a rant on the Swift forums about the poor state of Swift documentation. It came to nothing, but I want to reiterate a point I made then: Project Swift urgently needs a searchable, connectable language reference.

To be fair, Swift has a language reference: the eponymous section in The Swift programming language (TSPL) contains most of the information I would expect from such a feature. But this section is not well structured to serve as a real reference:

TSPL is not searchable

The TSPL website does not have a search field. Even if it did, I imagine it would be a site-wide full-text search, 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 keyword documentation as the main result. I don’t want to see the hundreds of pages that contain the word “if” in the body of the text.
I would love to be able to search scores. Imagine if you could look up a symbol like # and would show a list of all syntax elements that use that 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 large and complex language that most people don’t know all of the language’s features.}

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

TSPL is not linkable

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

Share a link to a specific attribute, such as @resultBuilder, it’s difficult if you know HTML and nearly impossible if you don’t (not to mention the wrong URL).

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

The reader experience is even worse 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 takes you to the top of the super-long page in Attributes, with no indication of where to find the information you’re looking for.

Each language construct, keyword, attribute, and compiler directive must have its own linkable page.

TSPL is wrongly structured

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

For example:

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

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

IDE Integration

I was careful to file a complaint about the documentation for Fast and not about the (equally bad) state of from Apple developer documentation. Swift is not limited to developing apps for Apple devices and I believe it is essential for Swift to position itself as a standalone project if it is to be perceived as a viable general-purpose language.

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

But once we have that language reference, Apple must, of course, integrate it with Xcode for offline search and contextual help. Imagine if you could Option click on not just the identifiers, but any token in a source file to see its documentation.

Some examples:

clicking on if case let would explain the pattern-matching syntax.
clicking on in would explain the various variants of closing expression syntax.
clicking on #fileID would show an example of the resulting string and compare with #file and filePath.
clicking on @propertyWrapper would explain what a property wrapper is and how you can implement it.
clicking on @dynamicMemberLookup would explain its purpose and what you must 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 (Options abbreviation, optional chaining, optional pattern matching, try?)
clicking on /// would list the magic words Xcode understands in document comments.