Re: The challenge for Cocoa's on-line documentation

FROM : Jeff LaMarche
DATE : Sat May 17 22:36:06 2008

On May 17, 2008, at 4:16 PM, Johnny Lundy wrote:
> I never had any problem with a language's documentation since 1970 
> with the IBM 360 Reference Manual. That is, until I came across 
> Apple's documentation of Cocoa. I have never been so frustrated in 
> my life.

<snip>
> The usual pattern for a User Guide & Reference Manual is for the 
> User Guide to have chapters corresponding to the areas of the 
> product, and the Reference Manual having a page or so listing all 
> the details of each element. The Apple docs have neither.

<snip>
> - tag
> Returns the tag.
> See also : setTag


I do not know where documentation you saw this, but Apple's 
documentation for NSControl states the following in the method 
description for tag:

"Tags allow you to identify particular controls. Tag values are not 
used internally; they are only changed by external invocations of 
setTag:. You typically set tag values in Interface Builder and use 
them at runtime in your application. When you set the tag of a control 
with a single cell in Interface Builder, it sets the tags of both the 
control and the cell to the same value as a convenience."

That seems pretty darn clear and concise to me. It says something 
equally clear in setTag:

Besides, tags are a fundamental concept in Cocoa. If you don't know 
what tags are, maybe the API isn't the right place for you to be 
spending your time right now. I'm sure most of us here don't want to 
read through a description of what tags are every single time they're 
mentioned in the documentation.

Jeff