> but is it really that hard to document these behaviors?
I imagine it is, given the bureaucracy of a big company. Apple's documentation has long been really dreadful, mostly nonexistent and where it does exist, usually incomplete and even wrong. I've assumed it was because the code itself is developed by isolated groups while the documentation presumably has to touch all sorts of people (publishing, translation, language checks, ...) in a kind of Conway's law.
However, hard or not, writing comprehensive documentation is quite doable. I have never been a fan of the Windows programming model but I have long admired not just MS's documentation but the amount of effort and commitment they obviously put in.
Apple cares about some things but in this regard it appears they simply don't give a shit.