How to Read iOS or Mac OS Programming Documentation

The toughest part for me to get started was reading the Apple Documentation on iOS or MacOS. When I got into more APIs it got more complex. You need to understand how to read API or proprietary code documents in order to understand how to create a piece of code, connect to web services or debug changes in code.

You will very often see the term DEPRECATED, which means a particular method name is no longer used. This is very important so let’s take a look at Apple Docs first:

This tells us that the object of type NSArray has many methods that you can call on it. They may be Instance or Class methods but they are all listed here. If you want to know what an object can do, you ask it for its type and come to the Class Reference site.

Notice there are many tasks you can call on an NSArray:

Notice the task with red text next to it that reads “Deprecated in…”. Like I said it says it was deprecated after a certain version of the OS. Now let’s suppose we want to know about a particular method we can use on this type of object, let’s look at initWithObjects, it only sounds natural that if we want to create an array, we would like to put objects in it:

This means that if you call our standard way of creating any object:

Object Class *objectPointer = Object Class alloc …

and then we insert that method signature -(id)initWithObjects:(id)firstObject…

we get this:

Object Class *objectPointer = Object Class alloc -(id)initWithObjects:(id)firstObject

we can start putting objects into our array object. Now let’s look at the correctly formatted code:

NSArray *myArray = [[NSArray alloc] initWithObjects:@”hi”, @”bye”, nil];

Notice we took out the -(id) at the beginning of the method signature because this forcibly has to return an NSArray object. And the reason we can add this method signature to the NSArray *myArray creation line is because we know that NSArray contains that method signature inside its Class file. We can make sure of this by using the Jump To Definition in Xcode!

Let’s do so for an example I just ran across. I had been working on a game using Cocos2d. This means I was using an API or library or third party code framework. These terms are usually interchangeable but they basically mean the same. When somebody or some company works on a bunch of code that helps you perform certain tasks. For example, Cocos2d creators worked on many Classes to create Cocos2d. One such class is CCAnimation which takes in frames and strings them together to create an animation. They recently released v.2.0 and this particular class changed some of its method signatures to include improvements I guess.

If I open my code in Xcode and try to run my old code, it crashes saying “Unrecognized Selector sent to instance”.

This means that instance of CCAnimation doesn’t recognize that old method or selector. Presumbale because they changed the old name to accommodate new structural changes. So I right click over the CCAnimation call in my code where the app crashed:

And when I Jump To Definition I will be taken to that Class Reference for that Class:

This gives me the Class Reference for CCAnimation, the one being used in my project, and tells me which methods the Class now implements. Now I just find the method which more closely matches my needs.

It’s important to learn how to go from a crash to the documentation which can help you fix that crash.