> If a macOS API generates that value and a macOS API modifies it and a macOS API consumes it, and users should only ever pass it around as-is and never screw with it directly, it’s opaque data and its internal workings are none of their business.
But that's not the case. You get to set mWordClockTime as part of the init [0]. If you can initialise a value, but aren't given bounds for the value, then the documentation has screwed up.
The value is something the developer can create, and pass in when creating any AudioTimeStamp, which you will be doing a lot of if you're dealing with sound.
This isn't an arbitrary value you can just rely on to be correct, there may be good reasons for altering the value, such as when splitting sound into several thousand chunks and rearranging them.
It's a part of the exposed API - it needs to be documented how it behaves.
For a different take on a similar problem, let's look at how PulseAudio handles it [1].
> pa_core doesn't have any interesting functions associated with it, it is just a central collection of all the components and globally relevant variables. You're not supposed to modify the fields, at least not directly.
This is how you abstract away an API safely. The dev knows up front that pa_core is the type that'll be used, and that other functions will be modifying the sample cache for them - that is, they can't supply a value directly to the type or they've entered unsafe behaviour.
They can go off and find the right setter.
What follows on that page is only a courtesy, and can clearly not be used safely in most programs. It doesn't need to be there at all.
So the dev finds [2], where they call the client to get the sample.
And whilst duration is a uint64, is also has a few more things in the docs, such as the value can be lazy, so you need to check it exists before using it, and the property can raise an error when you try to access it and it doesn't yet exist. You'll also find that this a property (so you won't be creating it), generated by an interface, and where to find that interface.
I mean, I'm not one to compliment PulseAudio's documentation. It is an awful mess, just like the internals.
But they've given us a lot more than Apple bothered to.
[0] https://developer.apple.com/documentation/coreaudiotypes/aud...
[1] https://www.freedesktop.org/wiki/Software/PulseAudio/Documen...
[2] https://www.freedesktop.org/wiki/Software/PulseAudio/Documen...