Documentation for the Swift 3+ Grand Central Dispatch

Is there somewhere a complete documentation on the Swift 3+ API for Grand Central Dispatch? The Apple docs are driving me mad with just a function name without any explanation. And of course most things are differently named in Swift then in the old and useful GCD Obj-C docs.

Example: It took me ages to find that dispatch_apply now is concurrentPerform. How am I supposed to know this without docs?

Any help would be very welcome.

2 Likes

It's worth creating bug reports for missing documentation.

I could only find SR-5725 for the missing dispatch_apply API.

The renamed APIs are listed in Dispatch/Private.swift and Dispatch.apinotes (see SwiftName:).

That would create thousands of bug reports as the Apple Swift documentation is a real pain to use. I liked the old one but they removed it. The one with the guides in it and not only half assed doc comments. I really wonder how others are able to work with the new system.

As a very new user, the constant "No overview available" sections (e.g., concurrentPerform()) are very frustrating. It'd be nice to be able to understand what these methods actually do.

Flashback to the bad old days of “Description forthcoming” in the early days of Cocoa. *shudder*

So this has a history? I'm shocked - even AmigaOS has useful documentation of everything available 8(

Language grows fast, developers jump on it en masse perhaps before the language should have been adopted by the wide community for production projects (hence the pain the community felt between Swift 1, 2, 3, and 4), big push to advance the language so it can be stabilised (still not the recommended / viable option for distributing binary libraries) which pushes for even faster change, etc... it is understandable that documentation may be suffering a bit.

A bit? It is nearly non existential - I'm not expecting a MSDN level documentation but at least doc comments for all public method, types etc

2 Likes

I am not saying you should not expect MSDN level documentation actually :). An almost $1 Trillion company should staff appropriately to pursue that too? People may say well, it is the phones and tablet HW that make boosts of profits... but hint hint... without a strong vibrant third party developers ecosystem and the apps they make... maybe the devices would also sell a bit less too.

3 Likes

Apple's documentation was better in the 80's and 90's. Inside Macintosh was complete enough that you could probably have reverse engineered the whole OS from it. I think Apple's laissez-faire attitude towards up to date documentation came from the NeXT acquisition.

So how do people cope with this state?

I'm in the process of writing a DAM and have more to fight with api docs then new language or app design...

1 Like

organizations which design systems are constrained to produce designs which are copies of the communication structures of these organizations.
— M. Conway

The teams working on the core language, foundation, dispatch, server, the package manager, etc are all different and probably mostly communicating through the forums and twitter (that's how it looks at least, I'm an outsider).

So the answer to your question is: google and stackoverflow.

That would create thousands of bug reports as the Apple Swift documentation is a real pain to use.

I'm failing to see the downside to that. Maybe with thousands of bug reports, the developers will actually do something about it.

1 Like

You mean besides me drowning in the work to create them? ;)

Ah, i thought you meant thousands of bug reports created by thousands of people.

As a newbie developer, I thought this was the norm. And on stack overflow is impossible to ask a newbie question. Good thing my google-fu skills are good enough. :slight_smile:

I started programming in Objective-C pretty much the day the released Project Builder and the documentation back then was pretty shocking (I was used to Microsoft's API documentation which was vastly better). It gradually improved over the years with some notable exceptions (e.g. the kernel extension api and device driver apis). Generally, it's pretty good now but the docs for new features like the Dispatch module lags behind.

Generally, C-level APIs have the worst documentation from Apple, even if sometimes it shows up as a man page rather than online documentation (looking at you, os_log). Now that docs.swift.org exists, perhaps we can start moving towards Swift having its own community-sourced and generated docs for the libraries it exposes.