Understanding Objective-C Reference Notation

Question

Can someone explain the documentation format for Objective-C:

e.g.,

+ (id)arrayWithObject:(id)anObject

1. Why the plus sign? Why a minus sign in certain circumstances? Can you guys help me understand exactly what the format is when these lines of code appear at the beginning of each task in the reference page?

2. What does it mean when a method is defined like this:

   -(NSString *)description
   

3. Why is the * there? Is it a pointer to something? Why is it formatted like that?

Answer 1

Why the plus sign? Why a minus sign in certain circumstances?

A plus sign means that the method is a class method. You call it on the class, and it returns an instance of the class. So: +arrayWithObject: would be called like this:

NSArray *myArray = [NSArray arrayWithObject:someObject];

This creates a single-element instance of an NSArray* called myArray, which contains a reference to someObject.

(For brevity, I'm not going to get into the memory management aspect of this method, except to say that autorelease will be called for you at the end of myArray's lifespan. Another variant of this method will return a retained instance of NSArray* that you must release on your own, which you may prefer if the array needs to live beyond the lifespan of the function it is in. Read through Apple's Memory Management Programming Guide, or go through an Objective-C tutorial or book. Understanding how to manage memory is critical for successful Objective-C development.)

A minus sign means that the method is an instance method. You call it on an instance of the class, and it returns something else, like a number or another object.

As an example, let's say we want to know the number of objects in the instance of NSArray we just made. So we call the -count method on myArray:

NSUInteger numberOfObjects = [myArray count];
NSLog(@"there are %u objects in myArray", numberOfObjects);

(Note there is no * before NSUInteger. That is because NSUInteger is not an object type, but just another name Apple uses for the unsigned int C data type.)

The declaration of the -count instance method is:

-(NSUInteger)count;

which will be explained below.

What does it mean when a method is defined like this: ... Why is the * there? Is it a pointer to something? Why is it formatted like that?

The following method:

-(NSString *)description

declares that we have an instance method called -description, which operates on an instance of the class (whatever that class might be, say an NSArray* instance) and returns an NSString* that gives the description of that instance.

Note that this method returns an NSString* and not an NSString. That's because these functions pass around references or pointers to objects, instead of the objects themselves.

If we call -description on myArray, assuming it contains someObject, then the Xcode console will show a description of myArray and its contents:

NSLog(@"%@", [myArray description]);

Note that Apple provides a shortcut where -description is called automatically on an object when used with NSLog(). So you could also do the following:

NSLog(@"%@", myArray);

in order to call -description on myArray.

Because calling -description on an object is redundant in an NSLog() statement, this second approach is preferred by Objective-C developers.

Answer 2

1. '+' means that the function is static while '-' means the function requires an instance. A static function is one which you don't need an instance and instead call on the class. Often these are initializers which will return an auto-releasing instance to you.

2. Yeah, that is because it is a pointer to an NSString objective C object

3. -(NSString *)description

This means that the class you are looking at the doc for has a method called description which when called on an instance of that class will return a pointer to an NSString object.