Re: Documentation frustrations
Re: Documentation frustrations
- Subject: Re: Documentation frustrations
- From: James Andrews <email@hidden>
- Date: Sat, 9 Jul 2005 01:52:54 -0400
I have to agree with Raffael. It is my personal opinion that the
Apple Developer Docs are obtrusively vague, unhelpful, incomplete and
worse yet poorly organized.
Here's a great example. (from someone who doesn't understand the
basics).......
http://developer.apple.com/documentation/Cocoa/Reference/
ApplicationKit/ObjC_classic/Classes/NSWindow.html
The docs for NSWindow class.
"- (void) setIsVisible(bool)flag" is not listed on the page, but
yet is part of the class as it is listed in Cocoa in a Nutshell, and
I have it working in my app to hide my window.
James
*cough* Who is now trying to figure out the basics..... *cough*
On Jul 9, 2005, at 1:32 AM, mmalcolm crawford wrote:
On Jul 8, 2005, at 10:14 PM, Raffael Cavallaro wrote:
No, it's the API reference for Application Kit.
The authoritative reference for Cocoa is ADC Home > Reference
Library > Documentation > Cocoa.
But that's precisely the point!
ADC Home > Reference Library > Documentation > Cocoa is *not* a
single, authoritative set of documentation. It is dozens of
different documents, of a number of different types -API
Reference, Conceptual Documentation, Sample Code, Q&As - none of
which take responsibility for being complete or up to date.
This is simply not true.
The whole documentation suite is intended to be up to date. If you
find this not to be the case, then it's a bug, and you should
report it -- have you reported the issue with NSSound?
It's no longer clear exactly what you want. If you're looking for
a "single authoritative" set of documentation for a given
framework, then you can go to the API Reference:
<http://developer.apple.com/referencelibrary/API_Fundamentals/
Cocoa-api-date.html>
I single out the API reference since it should - at least in
theory - provide a *complete, authoritative, and up to date
reference* for everything a developer can do using Cocoa something
which is not true of the other doc types. If the API Reference
became the core, then it would be scrupulously kept up to date,
not have Q&As added to it without even having pointers to them.
And as noted, if this is not true, then it is regarded as a bug.
Please let me know where else the API reference is deficient. As
far as Cocoa is concerned, as far as I am aware the API reference
has 100% coverage of all new API delivered in Tiger.
It would also have sample code embedded in it.
Again, it does to a reasonable and limited extent. As explained
before, it is rare that a single class can be used in complete
isolation, so the general policy decision is that more complex code
samples should reside in higher-level documents that aggregate
information across the framework or frameworks. If you find places
where you believe the API reference would benefit from code
samples, please file enhancement requests. And to reiterate once
more, if you feel this is the case in general, file an enhancement
request.
As it is, one has to consult far too many different documents to
get complete, authoritative and up to date documentation for
simple things.
Again, please let me know for what other simple things lack
complete, authoritative and up to date documentation.
And again it would be interesting if you could provide an outline
for the NSView drawRect: method.
mmalc
_______________________________________________
Do not post admin requests to the list. They will be ignored.
Cocoa-dev mailing list (email@hidden)
Help/Unsubscribe/Update your Subscription:
This email sent to email@hidden
_______________________________________________
Do not post admin requests to the list. They will be ignored.
Cocoa-dev mailing list (email@hidden)
Help/Unsubscribe/Update your Subscription:
This email sent to email@hidden