On Wed, 07 Mar 2012 11:40:41 -0800, David Duncan <david.dun...@apple.com> said: >On Mar 6, 2012, at 1:28 PM, Mikkel Islay wrote: > >> Does anyone know the reason why the UIKit-additions for NSString, NSValue >> etc. aren't mentioned in the respective class references in the Apple >> documentation for iOS? > >Category additions are documented separately from the main class. For example, >UIKit's NSString additions are in NSString(UIStringDrawing) (which you can >search for in the documetnation).
You can search if you know about it. The fact is that this organization is bad for the user (the programmer). There are two related problems: * Some categories (but not all - that's another problem, the inconsistency) are documented separately from the class on which they are a category. * There is no reference from the class page to the category page. Taken together, this makes the methods defined by the category pretty much impossible to discover. I'm sure *you* know about them, but the purpose of the documentation is to help the person who does *not* know, and in this regard it falls down completely. Here are some excerpts from my book, alerting the reader to this issue: ===== This organization won't matter to you as a programmer, because an NSString is an NSString, no matter how it acquires its methods, but it can matter when you consult the documentation. The NSString methods declared in _NSString.h_, _NSPathUtilities.h_, and _NSURL.h_ are documented in the NSString class documentation page, but the NSString methods declared in _UIStringDrawing.h_ are not, presumably because they originate in a different framework. Instead, they appear in a separate document, _NSString UIKit Additions Reference_. As a result, the string drawing methods can be difficult to discover, especially as the NSString class documentation doesn't link to the other document. I regard this as a major flaw in the structure of the Cocoa documentation. A third-party utility such as AppKiDo can be helpful here. ===== Of the methods injected into NSObject by categories, many are delegate methods used in restricted situations (so that these are really informal protocols), and do not need centralized documentation; for example, +animationDidStart:+ is documented under the CAAnimation class, quite rightly, because you need to know about it only and exactly when you're working with CAAnimation. Others that are general in nature are documented on the NSObject class documentation page itself; for example, +cancelPreviousPerformRequestsWithTarget:+ comes from a category declared in _NSRunLoop.h_, but it is documented under NSObject, quite rightly, since this is a class method, and therefore effectively a global method, that you might want to send at any time. However, every object responds to +awakeFromNib+, and it's likely to be crucial to every app you write; yet you must learn about it outside of the NSObject documentation, sitting all by itself on the _NSObject UIKit Additions Reference_, where you're extremely unlikely to discover it! m. -- matt neuburg, phd = m...@tidbits.com, <http://www.apeth.net/matt/> A fool + a tool + an autorelease pool = cool! Programming iOS 5! http://shop.oreilly.com/product/0636920023562.do _______________________________________________ Cocoa-dev mailing list (Cocoa-dev@lists.apple.com) 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: https://lists.apple.com/mailman/options/cocoa-dev/archive%40mail-archive.com This email sent to arch...@mail-archive.com
