Re: why are there zero examples in the cocoa docs?!

FROM : I. Savant
DATE : Sat Jan 19 21:36:24 2008

> why does the documentation suck so much (for beginners)? :-)


  A counter-question: Why do beginners always assume the trouble 
they're having with documentation is automatically the documentation's 
fault?

> am i researching the wrong place?


  Probably. There is a *lot* of documentation and, contrary to your 
opinion, many say that this is the best documentation they've seen for 
a platform / language / API. I'd tend to agree.

  No matter how well-written the technical specifications are for the 
design of every part of a given car, you're not going to be able to 
build a car just like it from scratch just by reading the individual 
specs of each of its parts. You've got to read the blueprint, the 
materials list, an overview of the sub-assemblies, etc.

  In short, you're going about this ass-backwards.

  The best place is the beginning:

Getting Started with Cocoa
http://developer.apple.com/referencelibrary/GettingStarted/GS_Cocoa/index.html

The Objective-C 2.0 Programming Language
http://developer.apple.com/documentation/Cocoa/Conceptual/ObjectiveC/Introduction/chapter_1_section_1.html

Cocoa Fundamentals
http://developer.apple.com/documentation/Cocoa/Conceptual/CocoaFundamentals/Introduction/chapter_1_section_1.html

Cocoa Application Tutorial
http://developer.apple.com/documentation/Cocoa/Conceptual/ObjCTutorial/01Introduction/chapter_1_section_1.html

  Take your time. I was a complete newbie to Cocoa a few years back 
and, though it was difficult and took awhile to pick up Objective-C 
and Cocoa's architecture, I found the documentation (and the books 
recommended on the Fundamentals page) invaluable and an excellent 
resource that's constantly improved.

  *There is no substitute for doing your research.*

> - (void)addChapters:(NSArray *)chapters withAttributes:(NSDictionary 
> *)attributes error:(NSError **)errorPtr
> so probably i have to call something like:
>
> [myMovie addChapters:myChapterArray]


  No, this is where reading the introductory material above 
(particularly the Objective-C guide) comes in handy (as well as a good 
working knowledge of C++, of which Objective-C is a superset). You 
have to call:

[myMovie addChapters:myChaptersArray 
withAttributes:myAttributesDictionary error:&someErrorPointer];

  You can't simply ignore the method signature. It's not the API 
reference's fault that you do not know Objective-C syntax. It's also 
not the API reference's job to teach it to you. That's the guide 
above's job. It's *your* job to read it.

> looking forward for the "initial hint" that will hopefully light the 
> spark :-)


  It sounds superior and smug, I know (and it is somewhat because 
it's a rather obvious concept), but that's really the best advice 
you're going to get: Read and re-read the introductory material until 
you understand it because you won't get anywhere without mastering the 
basics.

  If you get lost and have questions on what you're reading, post 
back to the list for clarification.

--
I.S.