In August 2020, I posted a rant on the Swift boards concerning the poor state of Swift documentation. Nothing got here of it, however I wish to reiterate one level I made then: the Swift challenge sorely wants a searchable, linkable language reference.
To be truthful, Swift does have a language reference: the eponymous part in The Swift Programming Language (TSPL) incorporates a lot of the info I’d anticipate from such a useful resource. However that part isn’t effectively structured to function an precise reference:
TSPL is just not searchable
The TSPL web site doesn’t have a search area. Even when it had one, I think about it might be a full-text search over the complete website, as is widespread (and applicable) for a ebook. A language reference wants a special search engine:
-
Trying to find key phrases (
if,case,the place) should reliably discover the documentation for the key phrase as the highest end result. I don’t wish to see the lots of of pages that comprise the phrase “if” of their physique textual content. -
I’d love to have the ability to seek for punctuation. Think about in case you may seek for a logo comparable to
#and it might present you an inventory of all syntax components that use this image. This might be very informative and a good way to discover the language, not only for inexperienced persons — particularly with good IDE integration (see under). Swift is such a giant and complicated language that most individuals gained’t know each language function.
A language reference wants a search engine that is aware of to deal with key phrases and punctuation.
TSPL is just not linkable
Pages in TSPL are usually lengthy, with many separate gadgets crammed right into a single web page. For instance, all compiler attributes are documented on a single web page.
Sharing a hyperlink to a particular attribute, comparable to @resultBuilder, is troublesome if you realize your manner round HTML and just about not possible in case you don’t (to not point out the dangerous URL).
As a reader, opening such a hyperlink is disorienting because it drops you in the midst of a really lengthy web page, 95 % of which is irrelevant to you.
The reader expertise is even poorer while you arrive from a search engine (as most individuals would as a result of the location has no search operate): TSPL is without doubt one of the high outcomes for swift resultbuilder on Google, however it drops you on the high of the superlong web page on Attributes, with no indication the place to seek out the knowledge you’re in search of.
Each language assemble, key phrase, attribute, and compiler directive ought to have its personal, linkable web page.
TSPL is structured fallacious
The Language Reference part in TSPL is organized as if it was written for parser or compiler builders. It makes use of the language’s grammar as a place to begin and branches out into expressions, statements, declarations, and so forth.
For instance:
I don’t learn about you, however as a person of the language, that’s not how I take into consideration Swift or how I seek for documentation.
Along with search engine, a language reference wants an alphabetical index of each key phrase or different syntax factor, with hyperlinks to the respective element web page.
IDE integration
I used to be cautious to make this a grievance concerning the documentation for Swift and never concerning the (equally poor) state of Apple’s developer documentation. Swift is just not restricted to app improvement for Apple gadgets, and I imagine it’s important for Swift to place itself as a standalone challenge if it desires to be perceived as a viable general-purpose language.
It’s good that TSPL is hosted on swift.org and never developer.apple.com, and that’s additionally the place this new language reference I’m envisioning ought to dwell. (I additionally suppose it’s fallacious to host the Swift API documentation on developer.apple.com.)
However as soon as we have now this language reference, Apple ought to after all combine it into Xcode for offline search and context-sensitive assist. Think about in case you may Choice-click not solely identifiers however any token in a supply file to see its documentation.
Just a few examples:
- Clicking on
if case letwould clarify the sample matching syntax. - Clicking on
inwould explains the assorted closure expression syntax variants. - Clicking on
#fileIDwould present you an instance of the ensuing string and evaluate it to#fileandfilePath. - Clicking on
@propertyWrapperwould clarify what a property wrapper is and how one can implement one. - Clicking on
@dynamicMemberLookupwould clarify its function and what it’s important to do to implement it. - Clicking on
<in a generic declaration would clarify what generic parameters are and the way they’re used. - Clicking on
?would present all language components that use a query mark (shorthand for Optionals, non-obligatory chaining, Non-obligatory sample matching,attempt?). - Clicking on
///would record the magic phrases Xcode understands in doc feedback.
You get the concept. This might be such a giant assist, not just for inexperienced persons.
To summarize, that is the unhappy state of looking for language options in Xcode’s documentation viewer:
guardian let me watch youtube else { throw match }
And this mockup reveals the way it might be:
