macOS Rant: Why is Apple so bad at documenting their stuff?

[foidulus]

I recently got into Cocoa programming and for the most part absolutely love it, Apple has obviously put a lot of effort into their system and it shows. However, Apple seemingly skimped on one of the most important, but usually easiest to implement parts of their system: good, up to date documentation!

For instance, in the QTKit documentation is just beyond abysmal. There is little documentation on how to do very common things, such as set your export settings. I had to do a lot of hackery just to figure that one out(and its still far from straightforward), they have typos that have been there for eons, even though I used their feedback form to tell them about it, and perhaps worst of all, they don't even mention many methods that are in the API.

On multiple occasions I have had to go into the header files just to find out what I could do with various classes. I shouldn't have to do this! Compare this experience with say, Javadocs and its night and day. While Javadocs are far from perfect, they are infinitely better than what Apple puts out.

Why would Apple do something like this? It costs them almost nothing to create a lot of these docs, and actually updating them once in a while could save developers tons of frustration. I guess maybe the paid ADC accounts are bit better? Thats really a low blow if they are though....

Sorry, just needed to blow off some steam. This whole thing is just doubly frustrating coming from a company like Apple who usually goes the extra mile to put a lot of polish in their products.

 

[GoCubsGo]

Pretty sure this falls under Steve Jobs' love affair with secrecy.

 

[Sayer]

QTKit is fairly new and it is probably getting written right now. There are only so many hours in a day, and you can't document an API that is in flux or is getting updated/changed constantly. Apple is working on QuickTime X and that may change a lot of stuff too, so there's no point writing documents on depcrated APIs.

And there is probably lot of info on the original QuickTime APIs that can apply in some cases such as formats supported, requirements for creating or playback and so on.

But in general, yes, Apple's documentation of the OS really sucks. We get better info from individuals using class dumps and gdb to figure out how stuff works.

 

[foidulus]

QTKit is fairly new and it is probably getting written right now. There are only so many hours in a day, and you can't document an API that is in flux or is getting updated/changed constantly. Apple is working on QuickTime X and that may change a lot of stuff too, so there's no point writing documents on depcrated APIs.

And there is probably lot of info on the original QuickTime APIs that can apply in some cases such as formats supported, requirements for creating or playback and so on.

But in general, yes, Apple's documentation of the OS really sucks. We get better info from individuals using class dumps and gdb to figure out how stuff works.

Certainly Apple has some sort of automatic documentation generator? Javadoc has been around for ages and if a little outfit like the one I work at can keep up their javadocs(really really simple if you document stuff right) why can't Apple keep theirs up?

2 of the methods have existed in all versions of qtkit(which dates back to early quicktime 7 versions) and the other has existed since Quicktime 7.2. Plenty of time for Apple to update their stuff. They just choose not to for whatever reason, and all it does is frustrate users.

 

[Cromulent]

Some stuff is left deliberately undocumented because they don't want people using it for whatever reason. Not saying this is specifically but there are undocumented parts of the system.

Microsoft are the kings of undocumented APIs though.

 

[foidulus]

Some stuff is left deliberately undocumented because they don't want people using it for whatever reason. Not saying this is specifically but there are undocumented parts of the system.

Microsoft are the kings of undocumented APIs though.

Yeah, but 99% of the time if they don't want people using something, they just make it a private API, or at the very least don't put the methods in the header. There are ways around that of course, but if you go breaking that then you obviously do so at your own peril.

My core question still remains though, why don't they have a system that automatically generates and distributes the docs? To me it just seems sloppy and incredibly puzzling.

They need to AVOID becoming Microsoft, so come on Apple, updating documents can only help you. The more devs you have for your platform, the better it is.

 

[HiRez]

I actually think Apple's docs are pretty good, but it does take them a long time to fill in the holes. For several years (at least) after Cocoa was first available, almost every entry said "Description forthcoming." under it. So yeah, QTKit is fairly new and they haven't caught up yet. I agree it could be better though.

 

[lee1210]

I would guess that apple does have an autodoc feature to run on their code to generate docs. So no, running such a tool on a new source file would not be hard. What might be hard is having documentation that is complete and fit to publish. They probably don't want the public doc for QTDoSomeCrazyThingOnlyTwoPeopleUnderstand to be:
"Does some crazy crap. Who in the hell knows what it does, what you should pass in, or why? I had to update the docs, and Bill's on sabbatical, so I can't ask him what this is for."

-Lee

 

[kainjow]

My guess is all of Apple's technical writers are too busy working on the iPhone SDK

 

[printf]

Microsoft are the kings of undocumented APIs though.

microsoft can afford to make this mistake because of the widespread use of their api's. codeproject.com, msdn forums, planetsourcecode - just tons and tons of resources and hundreds if not thousands of examples, tutorials and code repositories to search through. googling almost any win32 api results in overwhelming responses - even for its emerging technologies.

a little over two months ago, i began porting a thirty thousand line of code win32 app to the mac. i chose carbon because its language and api was the most closely aligned with the win32 api. now, carbon has been around a while, it's mostly matured and you would expect mountains of documentation and a plethora of resources to be tapped into via google - not so.

it's been a bittersweet uphill battle the whole way. this is not a simple form-based application where you drag and drop some buttons and menus on a few dialogs and throw in a few well-formed, nicely indented mvc-modeled object oriented lines of code - there are hundreds of functions that make use of some of the most obscure pieces of the win32 api - from font/type rendering to gdi/quartz - and trying to find and implement the carbon equivalent - a task highly reliant on good documentation has been met with a multitude of challenges along the way (and i won't even get into the deprecation issues here (atsui, anyone?)).

don't get me wrong - the api itself is very nice - well, the matured parts of it are, and visually my app looks beautiful! but a fine technology is only as good as its documentation.

i've been in this field a while. i've written win32 applications in c/c++, vb6, c#, vb.net. i've worked in the web industry, writing web-based applications in javascript, vbscript, c#, java, flash's actionscript 2.0 and 3.0 and through all of this i've never experienced the level of frustration trying to get examples, or documented explanations on an api as i have during this port.

if cocoa is the savior of the mac world, the day i sit down with it to once again tackle this port, i hope i'm met with a much better experience. but judging by the post of the thread starter, that time is still a ways off...

 

[Cromulent]

microsoft can afford to make this mistake

It isn't a mistake. The reason they don't document it is a) because they don't want people knowing about it b) because the API is likely to change so it will render applications useless and c) because it is not a vital API to the system.

Cocoa is vastly better documented than Carbon. If you want an easy port it would most likely be best to do it in Cocoa, not only because it is a higher level API but because there are just so many different resources for it. Plus Carbons future is not as assured as it once was.

 

[printf]

It isn't a mistake. The reason they don't document it is a) because they don't want people knowing about it b) because the API is likely to change so it will render applications useless and c) because it is not a vital API to the system.

i think you missed my point entirely. i'm referring more to the lack of examples that follow the api, or at least a little commentary on it's usage - because from my experience it's sparse.

here have a look at the right way of doing it:
http://livedocs.adobe.com/flash/9.0/ActionScriptLangRefV3/fl/controls/DataGrid.html

oh, and look at the bottom - live docs! don't drool.


i used the carbon example above because, well, it's what i used and because it's mostly a mature technology, so you WOULD expect good documentation, if at any time, at least near the end when they are talking about deprecating it.

i'd rather not get into a carbon vs. cocoa debate, but as for your comments on cocoa, have a look at what the industry is saying to apple lately: http://lists.apple.com/archives/carbon-dev/2008//Oct/index.html

 

[foidulus]

It isn't a mistake. The reason they don't document it is a) because they don't want people knowing about it b) because the API is likely to change so it will render applications useless and c) because it is not a vital API to the system.

Cocoa is vastly better documented than Carbon. If you want an easy port it would most likely be best to do it in Cocoa, not only because it is a higher level API but because there are just so many different resources for it. Plus Carbons future is not as assured as it once was.

That makes no sense, if they don't want people knowing about it, make it a private API or take it out of the header! If they are really changing their APIs that much then they really need to take a step back and ask themselves why. Also, for the stuff I was ranting about, I hardly doubt they would change the thing drastically. I want to add a QTTrack to a QTMovie, hardly an esoteric task. They didn't have this in versions of Quicktime prior to 7.2, and I think they just never bothered to update their documentation.

This gets me into another rant about how Apple deprecates APIs without actually providing an adequate replacement, but thats for another day.

 

[Cromulent]

That makes no sense, if they don't want people knowing about it, make it a private API or take it out of the header! If they are really changing their APIs that much then they really need to take a step back and ask themselves why. Also, for the stuff I was ranting about, I hardly doubt they would change the thing drastically. I want to add a QTTrack to a QTMovie, hardly an esoteric task. They didn't have this in versions of Quicktime prior to 7.2, and I think they just never bothered to update their documentation.

I was talking about Microsoft in that example if you see the post I quoted .

 

[foidulus]

I was talking about Microsoft in that example if you see the post I quoted .

mea culpa!

 

[DavidLeblond]

Microsoft are the kings of undocumented APIs though.

I'm not so sure, I've normally found MSDN to be quite helpful. On the contrary when I was learning to develop for the iPhone their documentation on it was abysmal and you couldn't ask questions in any forum because all the developers were sworn to secrecy. A lot of my knowledge came from trial and error.

 

[Cromulent]

i'd rather not get into a carbon vs. cocoa debate, but as for your comments on cocoa, have a look at what the industry is saying to apple lately: http://lists.apple.com/archives/carbon-dev/2008//Oct/index.html

Oh I know all about the Carbon mailing list . I've been subscribed to it for nearly two years.

 

[kainjow]

Someone explain to me why Apple will document a method/function but say it does nothing and might do something in the future. For example NSView's lockFocusIfCanDrawInContext: method:

This method was declared in Mac OS X v10.4, but is not used in that release. It currently does nothing and returns NO. However, it might be implemented in a future release.