Trying to understand -- please help...

FROM : Johnny Lundy
DATE : Wed May 21 21:37:41 2008

On May 21, 2008, at 3:03 PM, <email_removed> wrote:

> It is expected that you have at least looked at the getting started
> documentation before you attempt to dive much into anything else. You
> would quickly run across the following...
>


Well, that makes the point that some of us are trying to make. It may 
be "expected" by you, or even by Apple, but that is not relevant. What 
is relevant is what the person trying to USE the documentation 
"expects."

I submit that any experienced programmer looking up and turning to a 
page entitled "NSArray Class Reference" would "expect" that a behavior 
of the class that results in one's created object being deallocated 
out from under him would be documented in such a "Reference."

If he codes to what the Class Reference says, and his app doesn't 
work, that is in no way his fault.

This is just one example of that "little tidbit" that is always left 
out of these references by Apple. It seems to be the <.O. for some 
reason. The "tidbit" isn't some extraneous bell or whistle; it's 
always something fundamental.

They can't take 2 lines instead of 1 to document the behavior of a 
class method?

> <http://developer.apple.com/documentation/Cocoa/Conceptual/CocoaFundamentals/CocoaObjects/chapter_3_section_1.html#//apple_ref/doc/uid/TP40002974-CH4

> >
>
> Also note any verbiage talking about retain / autorelease, etc isn't
> (really) relevant if the garbage collection is being used.
>


Good point. Note that the NSArray Class Reference has verbiage about 
retain and release, and no verbiage about GC.


> -Shawn



I've been reading this documentation for six years. This 
incompleteness has bugged me the whole time. Conversely, the docs on 
AppleScript Studio and Carbon do not suffer from this problem - look 
up a Carbon C function and you're pretty much good to go.