Resolved Disambiguating Apple's documentation ... a mess

Discussion in 'iOS Programming' started by multinode, Mar 2, 2011.

  1. multinode, Mar 2, 2011
    Last edited: Mar 5, 2011

    multinode macrumors regular

    Joined:
    Feb 4, 2011
    #1
    Save the flames guys ... I know that to the Apple faithful this is going to be sacrilege ... so be it.

    In my many years of Mac programming (back to 1984), I've come to see Apple's documentation as a hodge podge. XCode techniques that don't consistently work (e.g. command-option double click doesn't always bring up a class reference and option double click likewise doesn't always work). I've seen extensions to classes band aided on (e.g. categories). And whereas iOS could have been a superset to MacOS, it's not ... e.g. table views in the two systems are handled completely differently! Apple needs to take time out from trying to squeeze every last bit of dollars out of its AppStore, etc and put some librarians to work cleaning up the documentation jungle ... otherwise the whole thing will collapse under its own weight.

    I spent a considerable amount of time trying to make sense out of the documentation. I'm going to summarize what I found. I would appreciate if some of the senior members here would correct any mistakes I've made and maybe append their own knowledge to this summary.

    1. In my MBP the paths to the Frameworks are:
    /System/Library/Frameworks (for MacOS)

    /Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator4.2.sdk/System/Library/Frameworks (for iOS Simulator)

    /Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS4.2.sdk/System/Library/Frameworks (for iOS)

    I'm not sure if the various .h files for a given framework are the same in all three worlds, but clearly the binaries are different because of the different processors.

    2. In the MacOS world it that the AppKit framework adds functionality to classes through the use of "categories" (indicated in parentheses below):
    a) NSColor (NSQuartzCoreAdditions) in NSColor.h
    b) NSColor (NSAppKitAdditions) in NSColor.h
    c) NSCoder (NSAppKitColorExtensions) in NSColor.h
    d) CIImage (NSAppKitAdditions) in NSCIImageRep.h
    e) NSAffineTransform (NSAppKitAdditons) in NSAffineTransform.h
    f) NSAppleScript(NSExtensions) in NSApplescript.h of the AppKit framework
    g) NSAttributedString (NSAttributedStringKitAdditions) in NSAttributedString.h
    h) NSAttributedString(NSStringDrawing) in NSStringDrawing.h
    i) NSAttributedString (NSAttributedStringAttachmentConveniences) in NSTextAttachment.h
    j) NSMutableAttributedString (NSMutableAttributedStringAttachmentConveniences) in NSTextAttachment.h
    k) NSBundle(NSBundleHelpExtension) in NSHelpManager.h
    l) NSBundle(NSBundleImageExtension) in NSImage.h
    m) NSObject (NSNibAwaking) in NSNibLoading.h
    n) NSBundle (NSBundleSoundExtensions) in NSSound.h

    3. In the iOS world it appears that the UIKit framework adds functionality to the classes through the use of "categories":
    a) NSObject(UINibLoadingAdditions) in UINibLoading.h
    b) NSCoder (UIGeometryKeyedCoding) in UIGeometry.h
    c) NSIndexPath (UITableView) in UITableView.h
    d) NSObject(UINibLoadingAdditions) in UINibLoading.h
    e) NSString(UIStringDrawing) in UIStringDrawing.h
    f) NSValue (NSValueUIGeometryExtensions) in UIGeometry.h
    g) NSCoder (UIGeometryKeyedCoding) in UIGeometry.h

    4. Categories ... the big elephant in the room. I got to all the above class extensions in a very round about way. In fact, I'm sure there are other extensions using categories that I missed. I know how to use categories to extend the functionality of my own classes, but how can I know this week's extensions (band aids) of Apple's built in classes? (Cynicism intended.)
     
  2. amorya macrumors 6502

    Joined:
    Jun 17, 2007
    #2
    I'm not going to flame you, but I don't think I agree.

    Why are you calling categories band-aids?

    They can be really useful. For example, the NSString AppKit additions, which allow NSStrings to draw themselves. It's part of AppKit, whereas NSString is part of Foundation. Since Foundation knows nothing of drawing to views, NSString itself can't have drawing methods. A category avoids the need for an NSDrawableString subclass.

    In terms of Apple's documentation, I guess it could be better. However, they usually do mention the appropriate categories in the preamble before a class: the NSString documentation says "Additionally, methods to support string drawing are described in NSString Application Kit Additions Reference, found in the Application Kit", as part of the overview at the top of the class.
     
  3. balamw Moderator

    balamw

    Staff Member

    Joined:
    Aug 16, 2005
    Location:
    New England
    #3
    Are these really changing weekly or is that just a bit of hyperbole?

    It seems like many of the things you are complaining about are documented in the framework where they are added. I'm not saying that the Apple documentation is perfect, but there is more to it than the header files.

    e.g. take a look at the AppKit Framework Reference
    http://developer.apple.com/library/...rence/ApplicationKit/ObjC_classic/_index.html

    I see (under Class References):

    CIColor Additions
    CIImage AdditionsNSAffineTransform Additions
    NSAppleScript Additions
    NSAttributedString Application Kit Additions
    NSBundle Additions
    NSCoder Application Kit Additions
    NSMutableAttributedString Additions
    NSString Application Kit Additions

    That, and skimming the release notes http://developer.apple.com/library/...oa/AppKit.html#//apple_ref/doc/uid/TP30000741 might be a better way of discovering these additions than searching the header files.

    B
     
  4. firewood macrumors 604

    Joined:
    Jul 29, 2003
    Location:
    Silicon Valley
    #4
    Companies that slow down to do this often get eaten by the competition.

    But I hear that the documentation for using ADA on IBM mainframes has been really extensive and clean for a long time. Why don't you program for that platform?
     
  5. multinode thread starter macrumors regular

    Joined:
    Feb 4, 2011
    #5
    Actually, I don't know how often Apple adds things with categories ... a bit of sarcasm.

    In fact, I did exactly as you did, i.e. I went to the AppKit Framework Reference first in order to discover the proper .h files. However, inasmuch as (for example) NSString is not subclassed, the only way for me to use the additions is to find the category that does the additions in the proper .h file and add it in parenthesis after NSString(xxx). That's backwards.
     
  6. chown33, Mar 2, 2011
    Last edited: Mar 2, 2011

    chown33 macrumors 604

    Joined:
    Aug 9, 2009
    #6
  7. multinode thread starter macrumors regular

    Joined:
    Feb 4, 2011
    #7
    Thank you CHOWN. Have you used this app? I'm always a bit nervous about early versions (this one is vs .985).

    Seeing the class hierarchy is certainly useful, but the bigger issue that I've tried to identify is the "categories" as applied to built in classes. From what I've seen, the only way to know about them is by visiting the proper .h file. That's backwards because one has to know that an addition exists for a particular class in the first place and then find the .h file in which the extended class is declared and then see the category that does the extending.
     
  8. multinode thread starter macrumors regular

    Joined:
    Feb 4, 2011
    #8
    Thank you BALAMW. As I think I noted in another response, I generated the summary list in my original post by doing exactly what you did vis-a-vis the AppKit Framework Reference, I still don't see any way to ascertain the category or categories that effect the extensions noted without visiting the .h files. Worse, I believe I saw other class extensions beyond the list you and I saw in the AppKit Framework Reference by randomly visiting .h files. So, thanks Apple for including additional functionalities to the built in classes, but that's useless unless you list all those categories, the classes they apply to, and the additional methods to which they refer. That should be a well known central document for all developers to see and it should be be regularly (not casually) updated.
     
  9. balamw Moderator

    balamw

    Staff Member

    Joined:
    Aug 16, 2005
    Location:
    New England
    #9
    I'm still struggling to see
    • How the Xcode built in Class Browser and the one chown33 linked to are deficient?
    • Why you need to use these classes and methods? if they are not extensively publicized and documented there may be a good reason not to use them....

    Just as an example. If I look up NSString in the Xcode Class Browser I find
    Code:
    drawInRect:withAttributes:
    listed along with all the other methods. Double clicking on it takes me right to the appropriate header file.

    I'm honestly confused by how this doesn't meet your definition of a central document (which in this case is updated regularly since it is self-generated from the headers)?

    B
     
  10. multinode thread starter macrumors regular

    Joined:
    Feb 4, 2011
    #10
    Thank you BALAMW. First, understand that I'm willing to be wrong and I'm not just trying to be picayune.

    My frustration actually started when I looked at someone's code where he was using the NSIndexPath class and referring to a "row" variable. I believe he was wrong because the native NSIndexPath class doesn't have a "row" variable. However, Apple added a category so that this variable is present as follows:

    Code:
    // This category provides convenience methods to make it easier to use an NSIndexPath to represent a section and row
    @interface NSIndexPath (UITableView)
    
    + (NSIndexPath *)indexPathForRow: (NSUInteger)row inSection: (NSUInteger)section;
    
    @property(nonatomic,readonly) NSUInteger section;
    @property(nonatomic,readonly) NSUInteger row;
    
    @end 
    And I don't see any way to know that category without going into UITableView.h ... sorry that's not intuitive to me.


    Another example. Here's one from UIApplication.h:
    UIApplication (UIRemoteControlEvents)
    The only way I found that was by arbitrarily looking at UIApplication.h ... there was no documentation pointing me to this.
     
  11. balamw Moderator

    balamw

    Staff Member

    Joined:
    Aug 16, 2005
    Location:
    New England
    #11
    I understand, and am not trying to flame you just trying to understand what you are looking for that isn't being provided...

    In the two examples you describe Apple does provide some documentation beyond what is in the header files and in both cases the header file is there in the Class Browser (as long as you Add Existing Framework to your project). So I don't understand why it requires you arbitrarily browsing the header files.

    e.g. for

    NSIndexPath

    Google for
    Code:
    NSIndexPath row site:developer.apple.com
    reveals

    http://developer.apple.com/library/...xPath_UIKitAdditions/Reference/Reference.html

    which takes you to the guide:

    http://developer.apple.com/library/...Paths.html#//apple_ref/doc/uid/TP40010167-SW1

    And the Class Browser reveals the header file.

    UIApplication (UIRemoteControlEvents)

    http://developer.apple.com/library/...lingiPhoneOS/RemoteControl/RemoteControl.html

    http://developer.apple.com/library/...Application/beginReceivingRemoteControlEvents

    And the Class Browser reveals the header file.

    B
     
  12. chown33 macrumors 604

    Joined:
    Aug 9, 2009
    #12
    If you have code open in Xcode, there's a gesture that takes you to its documentation: command option double-click.

    It requires Code Sense indexing enabled in Xcode's Preferences.


    And AppKiDo works fine for me. I've never had a serious issue with it. It's open source, so if you find an issue, you could fix it yourself.
     
  13. balamw Moderator

    balamw

    Staff Member

    Joined:
    Aug 16, 2005
    Location:
    New England
    #13
    Neat. That's much better than the right click Find Text In Documentation or Option Double Click.

    B
     
  14. multinode thread starter macrumors regular

    Joined:
    Feb 4, 2011
    #14

    Thanks BALAMW and CHOWN.

    Let's talk concretes ... not theory. I'm sure that Apple has probably documented all the category things I've mentioned above "somewhere". My problem is that there don't seem to be consistent ways to find these documentations. The need to stumble around and find things accidentally is not good for me. Beyond that:

    My original post came from this frustration: I was stepping my way through code in "iPhoneEchoClientViewController.m" and came to
    Code:
    - (void) tableView:(UITableView *)tableView didSelectRowAtIndexPath:(NSIndexPath *)indexPath {
    	 if (inputStream && outputStream) [self closeStreams];
        
    	 if (indexPath.row) {
    		NSNetService * selectedService = [serviceList objectAtIndex:indexPath.row];
    		if ([selectedService getInputStream:&inputStream outputStream:&outputStream]) [self openStreams];
    		serverLabel.text = [[serviceList objectAtIndex:indexPath.row] name];
    		}
    	 }
    
    Note the implication that indexPath contains an instance variable "row". Problem ... indexPath did not have the "row" variable in the XCode debugger. That issue led me to look at tableView.h in the UIKit framework where I found this:
    Code:
    
    // This category provides convenience methods to make it easier to use an NSIndexPath to represent a section and row
    @interface NSIndexPath (UITableView)
    
    + (NSIndexPath *)indexPathForRow:(NSUInteger)row inSection:(NSUInteger)section;
    
    @property(nonatomic,readonly) NSUInteger section;
    @property(nonatomic,readonly) NSUInteger row;
    
    @end
    
    I put this category code in "iPhoneEchoClientViewController.h" and picked up a couple of build warnings. Worse the "row" variable still didn't show up in the indexPath object in the debugger.

    So now I have a new problem ... I know the category extension on indexPath, but I don't know how to get it implemented in my code. :(

    Btw, command option double click doesn't always work. Option double click seems to work all the time (so far). That brings up a small window with two icons in its upper right corner ... one gets the class ref, the other gets the .h file.
     
  15. balamw Moderator

    balamw

    Staff Member

    Joined:
    Aug 16, 2005
    Location:
    New England
    #15
    There are several projects listed under "Related Sample Code" for these UIKit Extensions have you played with any of them to understand the problem better?

    AdvancedURLConnections
    iPhoneCoreDataRecipes
    ListAdder
    LocateMe
    TaggedLocations

    B
     
  16. chown33 macrumors 604

    Joined:
    Aug 9, 2009
    #16
    What do you mean by "put"? Do you mean you imported the declaration from TableView.h, or that you copied and pasted the source lines directly into your file? The former is sensible; the latter is not.


    I don't see how you inferred there is a 'row' variable. There is a 'row' property, but a property doesn't necessarily imply there's a variable.

    Even if there is a variable, it may not be named 'row', or it may not even exist as a named instance variable visible in the debugger.


    Exactly what warnings did you get?

    Copy and paste them into a post.


    Where did iPhoneEchoClientViewController come from?

    Google finds this:
    http://homepages.ius.edu/rwisman/C490/html/TCP.htm

    So are you using that class, or is the class something you wrote that just happens to have the same name?
     
  17. multinode thread starter macrumors regular

    Joined:
    Feb 4, 2011
    #17
    Thanks CHOWN.

    Important point CHOWN. Every description I've ever seen coupled a property with an instance variable so I tacitly assumed that a row variable was implied. Then I found this on page 78 of The Objective C Programming Language ... 2010-7-13:

    More later.
     
  18. chown33 macrumors 604

    Joined:
    Aug 9, 2009
    #18
    I don't see the direct relevance of @synthesize, nor of ivar synthesis in general.

    The 'row' property is declared in the interface for NSIndexPath(UITableView), and has the readonly attribute. An interface is not an implementation.

    @synthesize is only valid in the implementation of the property within the @implementation of a class. The header file does not contain an @implementation. It only contains an @interface.

    Unless you can come up with source that definitely shows an @synthesize for the 'row' property of NSIndexPath(UITableView) in an @implementation, you can't assume or infer that the property is implemented in any particular way.

    An implementation, especially for a readonly property, has any number of ways of producing the property's value. For example, the property need not exist as a separate variable at all; it may be calculated from other variables. For example, a Shape class may have an area property that's readonly and is calculated from other parameters of the Shape, such as height, width, diameter (if shape is circular), etc. There is no need to synthesize an area ivar, even though there is a readonly area property, and the property changes whenever any of its dependent values changes. Change height or width or diameter and the value returned as area changes.
     
  19. multinode thread starter macrumors regular

    Joined:
    Feb 4, 2011
    #19
    Hi Chown ... thanks

    Not to belabor the points made, I've learned a few things and I'll summarize them here for the benefit of others who are reading or will read this thread.

    Of course @property is located in the interface and of course @synthesize lives in the implementation. I brought up the notion of @synthesize in the context of legacy vs. modern runtimes. Every book and article that I've read about @property coupled it with the explicit declaration of relevant instance variables ... and these have been late copyright editions (always a good idea with a changing subject).

    So when my examination of TableView.h in the UIKit framework showed @property for row and section, I wrongly assumed that the existence of those instance variables was implied. In fact, I should have questioned the absence of those variables.

    I raised the issue of @synthesize because somewhere (hidden from us) the getter and setter methods for those instance variables are implemented by the compiler. The important issue that I raised (and you noted, too) is that the compiler may not call them by the names row and section in the current runtime.

    The other important point that I picked up along the way: by #import(ing) TableView.h in my interface, I automatically got the extended version of the NSIndexPath class in my final binary without needing to add anything myself.

    At the risk of being picayune, even your example of area may, in fact, imply the existence of that variable perhaps by a different name by the compiler. In fact, you use the dot notation for area and the runtime maps that to whatever name or method the compiler uses for that (perhaps temp) variable.

    'Nuff said ... we're on the same page. Anything more would convolute and confuse matters.

    Final notes ... Apple's documentation is seriously disorganized. And command option double click doesn't always work.
     
  20. seepel macrumors 6502

    seepel

    Joined:
    Dec 22, 2009
    #20
    I think this is where I would disagree. I think that it would be better if AppKit were deprecated by UIKit. UIKit is much more modern and makes more sense to me. I think a lot of the arguments made throughout this thread would be moot if this were the case. Just look at Twitter's new app. They basically rewrote UIKit rather than work with AppKit.
     
  21. multinode thread starter macrumors regular

    Joined:
    Feb 4, 2011
    #21
    I believe that what you are talking about is am implementation detail. I don't mean to trivialize what you've said ... probably valid. I'm thinking that much of what is done in MacOS could apply to iOS ... TableViews comes to mind immediately. iOS does TableViews with one column and we developers have developed ways to get around that by manipulating the construction of the cells, etc, etc (ugh!). I think either MacOS or iOS should be fixed so that TableViews are handled the same way in both systems. I'm guessing that there are other examples of inconsistencies between MacOS and iOS.
     
  22. balamw Moderator

    balamw

    Staff Member

    Joined:
    Aug 16, 2005
    Location:
    New England
    #22
    I still don't see what more you want? If Command-Option-Double click doesn't work, improve your Google-Fu, for both of the specific examples you raise there are guides, documentation of the extensions and code examples available.

    What specifically is it that Apple could do to make that more accessible to you?

    B
     
  23. multinode thread starter macrumors regular

    Joined:
    Feb 4, 2011
    #23
    Hi BALAMW

    I go back to the days of Inside Mac ... volumes 1 - 7. As with any print book/s topics were easily visible ... no accidental finds ... sort of a flat directory of topics. Non print documentation doesn't work well with a flat directory paradigm i.e. just appending topics onto the end of a list with no logical linking of subjects; that leads to us not knowing what we don't know. On the other hand non print documentation lends itself well to a tree organization. I would like to see a master tree visual of all the topics covered in the Cocoa and Cocoa Touch API's.

    Developers, in general, are not good organizers of written material ... too linear. At the micro level good commenting in code is too often an afterthought. Just as book publishers have editors to organize the materials submitted by authors, Apple needs more or better editors to organize its vast amount of documentation.

    In summary, there is not a shortage of documentation from Apple, but I and my colleagues (all senior people) too often find things accidentally ... not good. Wherever possible, MacOS and iOS should operate with identical concepts ... e.g. TableViews. And please Apple ... quit inventing new words. What Apple calls a dictionary is a database. English has been around for a long time ... cute substitutions of new words for those that we're all familiar with is an annoying obfuscation. Further, if you must invent a new word, then please give us a master glossary!
     
  24. balamw Moderator

    balamw

    Staff Member

    Joined:
    Aug 16, 2005
    Location:
    New England
    #24
    I'm more of a hardware guy, and go back to reading the schematics of the Apple II at the back of the reference manual so it's not that I don't feel your pain, I just don't think it's as important as you do for something as dynamic/flexible as Cocoa.

    I'm reminded of the story from "Cocoa in a Nutshell"

    These days looking it up includes using search engines to find information instead of just relying on the indices. Yahoo became a powerhouse by indexing and categorizing the early web, but today Google is king because they don't have to.

    B
     
  25. multinode thread starter macrumors regular

    Joined:
    Feb 4, 2011
    #25
    Ha ... I remember taking a colleague to a Palo Alto, CA store to help him shop for an Apple II for his son. And I still have my Altair 8080 in the garage.
    :)

    My problem with the docs is not earth shattering. George Warner (one of the gray heads at Apple once showed me the option command double click trick rather than traversing a nicely organized doc tree. So, yeah ... it's easier to ride the horse in the direction it's going (shrug).

    Thanks for all your inputs above ... helpful. Be well.
     

Share This Page