Sunday, September 25, 2022
HomeiOS DevelopmentSwift wants a greater language reference – Ole Begemann

Swift wants a greater language reference – Ole Begemann


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 need to reiterate one level I made then: the Swift venture 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) comprises a lot of the info I’d count on from such a useful resource. However that part isn’t nicely structured to function an precise reference:

TSPL shouldn’t be searchable

The TSPL web site doesn’t have a search subject. Even when it had one, I think about it could be a full-text search over the whole web site, as is frequent (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 outcome. I don’t need to see the tons of of pages that include the phrase “if” of their physique textual content.

  • I’d love to have the ability to seek for punctuation. Think about if you happen to might seek for a logo reminiscent of # and it could present you an inventory of all syntax components that use this image. This is able to be very informative and an effective way to discover the language, not only for newbies — particularly with good IDE integration (see beneath). Swift is such an enormous and complicated language that most individuals gained’t know each language characteristic.

A language reference wants a search engine that is aware of to deal with key phrases and punctuation.

TSPL shouldn’t be linkable

Pages in TSPL are typically 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, reminiscent of @resultBuilder, is troublesome if your approach round HTML and just about unattainable if you happen to don’t (to not point out the unhealthy 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 whenever you arrive from a search engine (as most individuals would as a result of the positioning has no search operate): TSPL is likely one of the prime outcomes for swift resultbuilder on Google, however it drops you on the prime of the superlong web page on Attributes, with no indication the place to seek out the data you’re on the lookout for.

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 find out 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 aspect, with hyperlinks to the respective element web page.

IDE integration

I used to be cautious to make this a criticism concerning the documentation for Swift and never concerning the (equally poor) state of Apple’s developer documentation. Swift shouldn’t be restricted to app improvement for Apple units, and I imagine it’s important for Swift to place itself as a standalone venture 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 reside. (I additionally assume it’s fallacious to host the Swift API documentation on developer.apple.com.)

However as soon as we’ve got this language reference, Apple ought to after all combine it into Xcode for offline search and context-sensitive assist. Think about if you happen to might Choice-click not solely identifiers however any token in a supply file to see its documentation.

A couple of examples:

  • Clicking on if case let would clarify the sample matching syntax.
  • Clicking on in would explains the assorted closure expression syntax variants.
  • Clicking on #fileID would present you an instance of the ensuing string and examine it to #file and filePath.
  • Clicking on @propertyWrapper would clarify what a property wrapper is and how one can implement one.
  • Clicking on @dynamicMemberLookup would clarify its objective 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-compulsory sample matching, strive?).
  • Clicking on /// would listing the magic phrases Xcode understands in doc feedback.

You get the thought. This is able to be such an enormous assist, not just for newbies.

To summarize, that is the unhappy state of looking for language options in Xcode’s documentation viewer:


Xcode documentation viewer showing meaningless results when searching for 'guard'
guardian let me watch youtube else { throw match }

Xcode documentation viewer showing meaningless results when searching for 'associatedtype'
Nope, this isn’t what I used to be on the lookout for.

And this mockup reveals the way it could possibly be:


Mockup of an imagined Xcode documentation popover for #fileID
Sure, I rebuilt Xcode’s documentation popover in SwiftUI for this mockup, syntax highlighting and all.
RELATED ARTICLES

LEAVE A REPLY

Please enter your comment!
Please enter your name here

20 − 14 =

Most Popular

Recent Comments