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?
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.
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.
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.
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.
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.
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.
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.