← Back to context

Comment by chmaynard

6 years ago

From the article:

"... Swift's Stabilized ABIs on Apple platforms ... are not actually properly documented, xcode just implements it and the devs will do their best not to break it. Apple is not opposed to documenting it, it's just a lot of work and shipping was understandably higher-priority."

Having worked in Apple's Developer Publications department for eleven years, I can confirm that this statement is mostly correct. Apple has the financial resources to hire more technical writers and properly document all their APIs, but it's just not a priority.

The sad thing is that developers outside Apple need this documentation and would even be willing to help write it. But they can't because, as a matter of policy, Apple does not generally involve the developer community in writing their official documentation.

28 comments

chmaynard

Reply
mojuba  6 years ago

In some areas Apple's documentation is dismal to the point of being ridiculously useless. Like this (from CoreAudio):

    mWordClockTime

    The word clock time.

And nothing else on that page apart from that it's UInt64. And it's been like this for years if not decades already. Nothing's changed since the APIs were also bridged and the documentation re-written for Swift. I doubt it's the intent (to keep the developers in the dark with regard to CoreAudio? unlikely), just neglect. Apple, otherwise one of the few companies that pays attention to details and have unlimited resources for this type of tasks, what's their problem really?

  • NovemberWhiskey  6 years ago

    In fairness, "word clock" is a term of art in professional digital audio: this is literally just a sample count so it is unit-less.

  • coldtea  6 years ago

    >And nothing else on that page apart from that it's UInt64.

    What else exactly do you need?

    It's a reference page for the members of the struct AudioTimeSTamp:

    https://developer.apple.com/documentation/coreaudiotypes/aud...

    I wish many C/C++ libs had such a good documentation...

    • shakna  6 years ago

      > What else exactly do you need?

      What unit it reflects. What epoch it uses. When does it wraparound? Is it realtime? Or best guess? Is it wall-clock like CLOCK_REALTIME or is closer to CLOCK_MONOTONIC? Is a valid range the entirety of possible uint64 values, or is there a range limit?

      8 replies →

gok  6 years ago

What exactly would a third party developer do with good documentation for the Swift ABI? The only practical application I can think of would be implementing some kind of Swift FFI, which has a realistic target market of fewer than 10 developers. And in practice, they would probably just use the Swift source code instead.

  • ckok  6 years ago

    Well considering the future of apis on osx and iOS is swift, any language that wants to target those needs to be able to talk to swift in the future.

    My compiler can do basic interop with swift now, but it's pretty much undocumented, unsupported, and when asking for any info the best I got, we're welcome for contributions on the docs. The docs that do exist are out of date and incomplete.

doe88  6 years ago

> Apple has the financial resources to hire more technical writers and properly document all their APIs, but it's just not a priority.

Related question, what is this seemingly reccurrent trope of Apple to continually understaff their teams/projects or behave as if they still were poor instead of throwing ressources at solving issues (e.g. better developer tools, better documentation, improving QA, ai, servers, reducing bugs, improving security...)? Is it greed? Is it the fear of growing too big and the cult of keeping teams small? Is it an inability to scale up sw projects? I'm dumbfounded by this strange behavior which more often than not lead them to unforced shortcomings.

  • chmaynard  6 years ago

    Great question.

    With respect to documentation, when I worked at Apple the understanding was that management thought developers could learn what they needed to know from reading the header files. Of course, that's nonsense. In reality, so much new software was being developed and shipped in each new release of macOS that it would have cost a fortune to document it in a timely fashion.