iOS Disambiguating Apple's documentation ... a mess

[multinode]

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.)

 

[amorya]

I'm not going to flame you, but I don't think I agree.

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.)

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.

 

[balamw]

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

 

[firewood]

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 ...

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?

 

[multinode]

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

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.

 

[chown33]

Get AppKiDo-for-iPhone.
http://homepage.mac.com/aglee/downloads/appkido.html

It does exactly what you're trying to do: browse the documentation primarily as a class hierarchy.

 

[multinode]

Get AppKiDo-for-iPhone.
http://homepage.mac.com/aglee/downloads/appkido.html

It does exactly what you're trying to do: browse the documentation primarily as a class hierarchy.

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.

 

[multinode]

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

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.

 

[balamw]

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.

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

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

 

[multinode]

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

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

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.

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:

// 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.

 

[balamw]

Thank you BALAMW. First, understand that I'm willing to be wrong and I'm not just trying to be picayune.

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

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

In iOS, UITableView and its delegate and data source use index paths to manage much of their content and to handle user interaction. To assist with this, UIKit adds programming interfaces to NSIndexPath to incorporate the rows and sections of a table view more fully into index paths. For more information, see NSIndexPath UIKit Additions. For instance, index paths are used to designate user selections using the tableView:didSelectRowAtIndexPath: delegate method.

And the Class Browser reveals the header file.

UIApplication (UIRemoteControlEvents)

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

In iOS 4.0, UIApplication has added methods and constants for managing background execution, for scheduling and canceling local notifications, and for controlling the reception of remote-control events.

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

And the Class Browser reveals the header file.

B

 

[chown33]

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:

// 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.

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.

 

[balamw]

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

Neat. That's much better than the right click Find Text In Documentation or Option Double Click.

B

 

[multinode]

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.

Neat. That's much better than the right click Find Text In Documentation or Option Double Click.

B

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

- (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:

// 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.

 

[balamw]

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.

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

 

[chown33]

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:

// 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.

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?

 

[multinode]

Thanks CHOWN.

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.

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:

Runtime Difference
In general the behavior of properties is identical on all runtimes (see Runtime Versions and Platforms in
Objective-C Runtime Programming Guide). There is one key difference: the modern runtime supports instance
variable synthesis whereas the legacy runtime does not.

For @synthesize to work in the legacy runtime, you must either provide an instance variable with the same
name and compatible type of the property or specify another existing instance variable in the @synthesize
statement. With the modern runtime, if you do not provide an instance variable, the compiler adds one for
you. For example, given the following class declaration and implementation:

@interface MyClass : NSObject {
float sameName;
float otherName;
}
@property float sameName;
@property float differentName;
@property float noDeclaredIvar;
@end
@implementation MyClass
@synthesize sameName;
@synthesize differentName=otherName;
@synthesize noDeclaredIvar;
@end

the compiler for the legacy runtime would generate an error at @synthesize noDeclaredIvar; whereas
the compiler for the modern runtime would add an instance variable to represent noDeclaredIvar.

More later.

 

[chown33]

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.

 

[multinode]

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.

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.

 

[seepel]

And whereas iOS could have been a superset to MacOS,

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.

 

[multinode]

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.

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.

 

[balamw]

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

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

 

[multinode]

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

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!

 

[balamw]

I go back to the days of Inside Mac ... volumes 1 - 7.

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"

It's practically impossible to know Cocoa inside and out. There was once a discussion between two programmers about Cocoa's large APIs: one was a veteran Perl programmer, the other a Cocoa programmer. The Perl programmer grumbled about the intimidating and verbose Cocoa APIs, saying there was simply too much to remember. Bemused, the Cocoa programmer retorted: "You don't remember Cocoa; you look it up!"

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

 

[multinode]

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

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.