Re: Trying to understand -- please help...

FROM : Sherm Pendley
DATE : Wed May 21 22:07:58 2008

On Wed, May 21, 2008 at 2:35 PM, Johnny Lundy <<email_removed>> wrote:

> Here's why the OP was not aware of the behavior of an NSArray class method:
> Here's the verbatim documentation for +arrayWithObjects:
>
>  arrayWithObjects:

>> Creates and returns an array containing the objects in the argument list.
>>

>
> See? Not a word about autoreleasing anything, or having to retain the
> returned array. Nada.



There's no good reason there *should* be anything about that in this method
description. The same standard pattern that's applicable everywhere and
*thoroughly* documented applies here too:

    <
http://developer.apple.com/documentation/Cocoa/Conceptual/MemoryMgmt/MemoryMgmt.html
>


Seriously, read that assuming you wanted to try out the NSArray class and
> tell me how it accomplishes its purpose of documenting what it is intended
> to document. It doesn't. And this pattern is repeated over and over in just
> about every one of the "Class References."



Your assumption is flawed. Anyone who tries to use reference material as a
tutorial is learning Cocoa the hard way. It's like trying to learn English
from a dictionary, and your proposed "solution" like including a
grade-school grammar introduction with dictionaries.

Further, the class documentation is intended to document the NSArray class,
including any exceptions to the standard Cocoa conventions and patterns. It
is specifically and by design *not* intended to document universal patterns
that apply to every class and method. The documentation writers didn't
intend to write the docs your way and fail to do so, they intended to write
it the way it's written.

sherm--

--
Cocoa programming in Perl: http://camelbones.sourceforge.net