Re: Serious Questions - count of missing API descriptions
Re: Serious Questions - count of missing API descriptions
- Subject: Re: Serious Questions - count of missing API descriptions
- From: tyler <email@hidden>
- Date: Mon, 28 May 2001 16:33:36 -0700
And to put some metrics on this issue of lacking documentation:
There are 205 instances of "Description forthcoming" in the Foundation
ObjC_classic class documentation files alone.
There are 429 instances of "Description forthcoming" in AppKit
ObjC_classes
That's 634 _specific_ descriptions that are missing. I don't have
time to compute a percentage, but that doesn't really matter. This
number means that in 634 different cases where I go to look for an
answer about a method or class I will find nothing.
This doesn't include the descriptions that may be incorrect, or contain
some other place-holder besides "Description forthcoming".
And that's only AppKit and Foundation. There are quite a few other
frameworks one could count and then there are the ones that don't even
have placeholder documentation... (CoreMIDI, CoreMIDIServer, CoreAudio,
Message, etc)
Kernel has 118 cases of "placeholder", IOKit has 18, etc.
SO, I think Brian has a point and I think apple needs to get on this
ASAP.
peace,
tyler
On Monday, May 28, 2001, at 12:02 PM, tyler wrote:
On Saturday, May 26, 2001, at 03:04 PM, Brian Howard wrote:
On Saturday, May 26, 2001, at 05:53 PM, Finlay Dobbie wrote:
There are holes in Apple's Cocoa documentation, but it's not THAT
bad. It's well organized, and the docs for most of the main classes
are pretty understandable. The main focus has been Carbon because
that's what matters at the moment - porting the OS 9 base of
applications to OS X is the prime concern for most developers. The
Cocoa documentation could be a whole lot better, but it's not as bad
as you make it out to be.
-- Finlay
That is probably true from your prospective. But those holes in
Apple's Cocoa documentation look a lot larger when you are also
standing in a hole, struggling to climb the mountain. As for Carbon:
I really gave that some thought, because it was plain that there was
tons of legacy docs and examples; but I decided to get into this
because of what Quartz can do, so there I am.
I agree with you Brian. And I am an experienced Mac OS programmer
(every version pre OS X back to 1983 on a Lisa).
To hear apple asking developers to hurry up and make their native apps
(WWDC) is almost funny given the serious unfinished state of
documentation. I'm not saying that one can't figure out what is
needed by reading all sorts of stuff all over the place (vermont
recipes, samples, mailing list archive snippets etc etc), but this is
not at all "good documentation" or "well documented" in my opinion.
It needs to all be in one well organized, indexed place. Inside
macintosh was pretty good that way (at least at first when it included
everything -- as the os evolved it got worse, but was still better than
many).
There was an application called Think Reference from Symantec way back
when (System 6 days was when it was best) that allowed one to type in
ANY api call and it would provide the definition, documentation on the
arguments, sample code for key ones, etc.
Apple needs to produce something similar for cocoa and we need it
yesterday. Now it appears that they are trying to do this with their
lame help viewer app and some kind of integration with the development
environment. Now this could be workable, if it worked and if all the
documentation was there.
At WWDC Jobs claimed that there were 1000 developers working on OS X to
make it better. That means there needs to be _at_least_ 100 people
working on developer documentation. Anyone want to guess how many
there actually are? 10? 20?
SO, I agree with Brian and at the same time I thank all those who
provided links to samples etc.
tyler
_______________________________________________
cocoa-dev mailing list
email@hidden
http://www.lists.apple.com/mailman/listinfo/cocoa-dev