Re: Documentation frustrations
Re: Documentation frustrations
- Subject: Re: Documentation frustrations
- From: mmalcolm crawford <email@hidden>
- Date: Fri, 8 Jul 2005 22:32:48 -0700
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