8 ms·

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

by mojuba 7y 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?

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 ago
    Also, 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 ago
    The 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 ago
      There 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
        Even if it counts in picoseconds it’ll take several centuries to roll-over, so these probably aren’t questions you ever need to ask. Though that’s kind of the point: the API and its documentation should highlight the stuff you need to worry about, such as where you get these values from and what they do, and hide everything else that you don’t (internal implementation details). But that particular API does the opposite. Just typedef-ing that data as an opaque `WordClockTime_t` would go a long way to fixing this, telling API users to ignore how it works internally and enabling automated documentation tools to to locate and list every other API that produces/consumes this particular value. A simple automation-friendly abstraction that would reduce—if not eliminate—the need for additional manually-written documentation. i.e. Put the knowledge in the code and the automation can graph it. Alas, there’s something about C programming that seems to bring out the worst abstractions in many C programmers… and if they’re being lazy in their API design, they’ll be twice as lazy when it comes to manually documenting it. -- "What is wrong with giving tree, here?" "Well, he don't know talking good like me and you, so his vocabulistics is limited to 'I' and 'am' and 'Groot.' Exclusively, in that order."
saagarjha 7y ago
That’s much better than some of the other “documentation” that Apple has…
NovemberWhiskey 7y 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.

by mojuba 7y ago

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 ago
  Also, 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 ago
  The 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 ago
    There 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
      Even if it counts in picoseconds it’ll take several centuries to roll-over, so these probably aren’t questions you ever need to ask. Though that’s kind of the point: the API and its documentation should highlight the stuff you need to worry about, such as where you get these values from and what they do, and hide everything else that you don’t (internal implementation details). But that particular API does the opposite. Just typedef-ing that data as an opaque `WordClockTime_t` would go a long way to fixing this, telling API users to ignore how it works internally and enabling automated documentation tools to to locate and list every other API that produces/consumes this particular value. A simple automation-friendly abstraction that would reduce—if not eliminate—the need for additional manually-written documentation. i.e. Put the knowledge in the code and the automation can graph it. Alas, there’s something about C programming that seems to bring out the worst abstractions in many C programmers… and if they’re being lazy in their API design, they’ll be twice as lazy when it comes to manually documenting it. -- "What is wrong with giving tree, here?" "Well, he don't know talking good like me and you, so his vocabulistics is limited to 'I' and 'am' and 'Groot.' Exclusively, in that order."

saagarjha 7y ago

That’s much better than some of the other “documentation” that Apple has…

NovemberWhiskey 7y 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.