Correct Documentation

[Gil]

Hi–

I’m using the Cocoa documentation in XCode Version 3.2.5 → Help → Developer Documentation (option-command-?).

I’m finding what seem to me to be little errors* in this documentation, which prompts me to ask: Am I using the correct Cocoa documentation?

I don’t mean to be picky. I’m just wondering if I should be looking at a different version of the Cocoa documentation.

–Gil

*- What I’m calling “errors” could very possibly be my misinterpretations. Here’s one example:

NSArray Class Reference → Instance Methods → description says:

Returns a string that represents the contents of the array, formatted as a property list.

• (NSString *) description

Apparently NSArray’s ‘description’ method actually returns an NSArray of NSStrings:

--'MyCalendars' is (I think) an NSArray of CalCalendar instances
log "description of MyCalendars=" & (description of MyCalendars)
--> Can't make description of «class ocid» id «data kptr00000000A0A3620002000000» into type Unicode text.
log "description of MyCalendars=" & (description of MyCalendars as list)
--> A concatenation of descriptions, one for each CalCalendar instance.

Here’s another:

CalCalendarStore Class Reference → Instance Methods →

There is no ‘description’ method listed, even though

log "description of SharedCalendarStore=" & description of SharedCalendarStore
--where SharedCalendarStore is an instance of CalCalendarStore

produces a reasonable result.

Model: MacBook Pro
AppleScript: 2.1.2
Browser: Firefox 3.6.13
Operating System: Mac OS X (10.6)

[rdelmar]

Apparently NSArray’s ‘description’ method actually returns an NSArray of NSStrings:

What you see in ASOC when you use the log command isn’t necessarily what you get in Objective-C, for which the documentation is written. If you do this in Objective-C with an array called theArray:

NSLog(@“%@”, [[theArray description] class])

you get NSCFString as the result.

CalCalendarStore Class Reference → Instance Methods →

There is no ‘description’ method listed, even though

That’s because of inheritance – CalCalendarStore inherits methods from NSObject which does have a description method.

Ric

[Shane_Stanley]

@rdelmar

That’s because of inheritance – CalCalendarStore inherits methods from NSObject which does have a description method.

Let me again suggest that people try AppKiDo. It’s a free documentation viewer – it presents the same info but in a different format – and it gives you the option of listing inherited methods.

[Gil]

@rdelmar

If you do this in Objective-C with an array called theArray:

NSLog(@“%@”, [[theArray description] class])

you get NSCFString as the result.

Thanks, Ric. That’s very helpful. Implicitly, you are suggesting that I’m using the right documentation, which is very valuable information itself.

NSObject which does have a description method.

NSObject, thus all all objects, has a description class method. That’s handy. However, it was the instance method I was looking for when I invoked ‘description’ for that NSArray instance. I suppose that’s why ‘description’ appears in the NSArray Class Reference and not all others.

When I sent the ‘description’ message to an instance of the CalCalendarStore class, I must’ve got the class method. The string that it produced shows only class information, nothing particular to the instance.

Another handy-looking NSObject class method is ‘class’, which you used above. Unfortunately, I suppose, or else you would have shown us in your example, there’s no way inside AppleScript to coerce what it returns to a string, as NSLog appears to do.

Is there? I’ve tried |class| of someInstanceVariable, but it didn’t seem to work (“Can’t make |class| of «class ocid» id…”.) Pity.

–Gil

[Gil]

@Shane Stanley

Let me again suggest that people try AppKiDo… it gives you the option of listing inherited methods.

Thanks for the tip, Shane. I’ll give it a whirl.

–Gil

[Shane_Stanley]

@Gil

[When I sent the ‘description’ message to an instance of the CalCalendarStore class, I must’ve got the class method. The string that it produced shows only class information, nothing particular to the instance.

There’s a lot of variety in how description is implemented, FWIW.

Another handy-looking NSObject class method is ‘class’, which you used above. Unfortunately, I suppose, or else you would have shown us in your example, there’s no way inside AppleScript to coerce what it returns to a string, as NSLog appears to do.

You could try something like this:

set x to (current application’s NSString’s stringWithFormat_(“%@”,'s |class|())) as text

[Gil]

You could try something like this:

set x to (current application’s NSString’s stringWithFormat_(“%@”,'s |class|())) as text

It works! Thanks!

I find it interesting you put parentheses after |class|(). I tried taking them out and it still worked. What’s the theory here?

Your success inspired me. I came up with another way to do it:

		log "class of NextPeriodPredicate=" & ¬
			description of (|class| of NextPeriodPredicate) -->CalEventPredicate
--where NextPeriodPredicate is a local variable containing indeed an instance of CalEventPredicate

Now we’re on a roll…

Thanks, Shane!

–Gil

[Shane_Stanley]

@Gil

I find it interesting you put parentheses after |class|(). I tried taking them out and it still worked. What’s the theory here?

You’re calling a method, and I prefer the consistency of all such calls ending with parentheses, to distinguish them from variables. Just a matter of preference, really.

[Gil]

@Shane Stanley

You’re calling a method, and I prefer the consistency of all such calls ending with parentheses, to distinguish them from variables.

Nice idea. I think I will adopt it.

BTW, I bought Explored from Kagi yesterday. I’m reading it through first without working the tutorials. I’m on page 35. Fascinating read. I like your writing style. Thanks for writing it for us.

–Gil

[Shane_Stanley]

I’m glad you’re enjoying it! But do try the tutorials at some stage.

[Gil]

Oh, yes. I had no idea Tables were so powerful! I’ve dreamed up a killer app and those tutorials are going to lead me right to it. Thanks for explaining so clearly how to make them work.

Thanks for your help, Shane.

–Gil