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:

NSArray Class Reference
Santiapps. Marcio Valenzuela. Learn to program for iOS or MacOS

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:

5. NSArray Class Reference
Santiapps. Marcio Valenzuela. Learn to program for iOS or MacOS. Understand how to read NSArray Class Reference.

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:

6. NSArray Example
Santiapps. Marcio Valenzuela. Learn to program for iOS or MacOS. Understand how to read NSArray Class Reference.

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

1. XCode Console debugging
Santiapps. Marcio Valenzuela. Learn to program for iOS or MacOS. Understand how to read NSArray Class Reference.

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:

CCAnimation Definition
Santiapps. Marcio Valenzuela. Learn to program for iOS or MacOS. Understand how to read NSArray Class Reference.

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

3. CCAnimation Definition
Santiapps. Marcio Valenzuela. Learn to program for iOS or MacOS. Understand how to read NSArray Class Reference.

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.

2 Replies to “How to Read iOS or Mac OS Programming Documentation”

  1. Since I am a huge fan of great customer service, it
    meant a lot to have a response in less than 40 minutes.
    Now then, can we design autonomous cars to understand when they
    are getting into trouble, when their visual sensors are overloaded and the computer system can’t process the information fast enough to stay safe. You may already know that animation includes 2D and 3D computer animations.

Leave a Reply