On Wed, 13 Apr 2011 12:32:27 -0700, Kyle Sluder <[email protected]> said: > >I don't know what it is about Apple's documentation, but something >about it trips everyone up when they first get to the platform. I'm >certainly among that crowd. It's not that things aren't sufficiently >documented; usually they are, with certain notable exceptions like >Core Audio.
I would point to Core Animation, which omits or gets wrong a number of key (hint) fundamental facts. >Maybe it's that you really do need to be willing to make >plenty of clicks in order to understand small facets of the thing >you're looking at. On top of that, you really do need to understand >the whole of a class before you can proficiently work with it. This is why my book has a chapter on documentation where I actually take the reader through a typical page of class documentation, while jumping up and down and yelling "don't forget to look in the superclass", "don't forget to look in the adopted protocols", and so on with all the other lessons I've learned over the years. Nonetheless, although I think the docs have become *vastly* better cross-linked than they used to be (and don't think I don't appreciate it!), the business of documenting things in multiple files, often *without* linkage of any kind, remains one of the documentation's greatest weaknesses. (My favorite examples are things like the string drawing methods and awakeFromNib - indeed, NSObject itself is very scattered and quite hard to get a complete handle on.) AppKiDo can be a help here. And in the end, of course, documentation is only that - documentation. A list of methods and functions is not knowledge. Docs cannot be reasonably expected to have explanatory or (perhaps I should say) instructive power as well. It can often take a great deal of experimentation before the penny drops and the pieces of a framework or technology start to gel in your mind and you start to see when and how to use it. m. PS In the particular case of MPMoviePlayerController, where the OP was having trouble tracking down a play command, my book has: "Further programmatic control over the actual playing of the movie is obtained through the MPMediaPlayback protocol, which MPMoviePlayerController adopts. This gives you the expected play, pause, and stop methods, as well as commands for seeking quickly forward and backward..." I had trouble discovering this too, the first time! I like to think that I've suffered so you don't have to... :) -- matt neuburg, phd = [email protected], <http://www.apeth.net/matt/> A fool + a tool + an autorelease pool = cool! Programming iOS 4! http://www.apeth.net/matt/default.html#iosbook_______________________________________________ Cocoa-dev mailing list ([email protected]) Please do not post admin requests or moderator comments to the list. Contact the moderators at cocoa-dev-admins(at)lists.apple.com Help/Unsubscribe/Update your Subscription: http://lists.apple.com/mailman/options/cocoa-dev/archive%40mail-archive.com This email sent to [email protected]
