10 ms·
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
by chmaynard 7y 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.
- mojuba 7y agoIn 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?
- coldtea 7y 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/audiotimestamp https://developer.apple.com/documentation/coreaudiotypes/aud... I wish many C/C++ libs had such a good documentation...
- Tempest1981 7y ago> What else exactly do you need? I always like to know the units (seconds? nanoseconds?) and the reference-year (1970? 2001? 1601?)
- vunie 7y agoAlso, how are leap seconds reflect in this value if at all? Apple should look at linux's manpage on the `time` syscall for inspiration.
- shakna 7y 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?
- justsid 7y agoThe answer is “not applicable” to all of these. The word clock is unit less, just ticking up each sample. It’s not actually a clock in the normal sense, there is no leap years or anything in it. It’s used to synchronize devices. Granted, the documentation isn’t the best at explaining it. But if you know what a word clock is in terms of audio, you know what the value is; a counter.
- TheOtherHobbes 7y agoThere is a glossary in the CoreAudio docs, but it hasn't been updated since 2010. And it doesn't include an entry for WordClock. You could argue that generally the docs are good enough to Get Shit Done. And people are Getting Shit Done on the platform as a whole. So there's no problem. But it's a shame Apple doesn't consider better docs a priority. IMO it's not a good look for a trillion dollar company. More, I don't know if insiders use the same doc base. If so it's definitely wasteful, because newcomers are going to be wasting time and effort trying to get up to speed.
- shakna 7y ago> The word clock is unit less, just ticking up each sample. That should be in the documentation. Each sample is guaranteed to have an increment compared to a previous sample. But, it doesn't answer all of the questions. Does the world clock always start from 0? Is that an assumption that can be made? Or is the valid range anywhere inside a uint64? What happens if the number of samples exceeds the length of the world clock unit? Is it allowed to overflow? In which case it violates the assumption that it always just increments.
- hhas01 7y ago
- saagarjha 7y agoThat’s much better than some of the other “documentation” that Apple has…
- NovemberWhiskey 7y agoIn fairness, "word clock" is a term of art in professional digital audio: this is literally just a sample count so it is unit-less.
- gok 7y agoWhat 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.
- saagarjha 7y agoFunction hooking is a lot more popular than you think it is.
- pjmlp 7y agoAnd usually forbidden in modern sandboxing.
- saagarjha 7y agoSandboxing has almost nothing to do with (and does not prevent) function hooking.
- pjmlp 7y agoTrue, they are orthogonal. However Windows, xOS and Android sandboxing are relatively restrictive in that use case.
- saagarjha 7y agoHow so? With dynamic linking function hooking is not all that difficult.
- pjmlp 7y agoFor the stuff that comes with your own package sure, but don't expect to override all the OS libraries without eventually get the process killed, like trying to use DLL injection and OS Hooks on Windows.
- Rapzid 7y agoDevelopers should be documenting the APIs at a bare minimum.
- doe88 7y 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 7y agoGreat 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.