What’s the real difference? It’s the same with good testing. Engineers are expected to operate on timelines and meet deadlines that are often not generated by someone who values good testing and thorough documentation. If Apple wanted good documentation they would have to be comfortable with something that was going to take one week now taking two weeks and they’d probably need to include willingness and ability to document as something they select for when hiring. Or they’d have to spin up documentation teams that work alongside feature engineers, or something. In almost every environment I’m been in, people balk when you force them to confront the reality that good quality things take time and effort. So I don't think it’s just a careless “whoops we forgot to tell the engineers to document” type of scenario. I think it is fundamental to the fabric of the company and those that operate it.

I mean, generating a list of classes and their members, hierarchies and relationships, with basic annotations, is the easiest, most mechanically automated solution possible. Apple's bizarre documentation seems like it would take significantly more work.

It truly seems philosophical. Someone there thinks this is a superior solution.