Tips for Reading Apple’s iOS Documentation

Apple iOS documentation is pretty good as far as documentation goes, but it does have many problems and quirks that you need to watch out for if you want to be an expert in iOS. After you have used it a while it can be a great resource, and is the first place I look when I have any questions. Other times I know that the documentation won't help and I am better off looking for a blog post, or stackoverflow for an answer.

Structure of the Documentation

The best thing about the documentation is its strict structure. Once you understand where everything is it become much easier to read it, and to find what you are looking for. A table of content is shown on the side of page and will often show "Overview", "Tasks", "Properties", "Class Methods", "Instance Methods", and "Constants". Each Method is described in the same way, it has a summary, a list of parameters, Discussion and in which iOS version the method became available.

If it is the first time I am looking at a class I always read the Overview text. In this text Apple explains what the class does, how to properly subclass, and what you should watch out for. If you are accustomed to not reading it, you are making a mistake. It is important to get in the habit of reading them because it often contains information which is not immediately apparent when first looking at the class.

When I started in iOS I often overlooked the section right at the top of the page, but over time I found myself looking more and more at it.. There is a list of basic information about the class. I used to gloss over this section. For me the most important is Inherits From show the inheritance chain of the Class. Not only does it show the superclass, but all of the superclasses up to NSObject. If you are looking for a particular function or property somethings you have to think if this is really in the superclass. Likewise it is important to scan the Conforms To as there is often methods that are "hidden" here.

The documentation doesn't teach concepts well

The first thing you need to know about the documentation is that it is not a place to start learning iOS. You cannot start reading the documentation for an introduction into how UIViewController are supposed to work, or understand good separation of Model-View-Controller. Even the companion guides often assume more than a basic understanding of Apple programming topics.

If you want to start with iOS, the documentation is NOT the place to start. If you don't know the difference between a UIView and UIViewController I would recommend the Standford Introduction to iOS lecture .

The documentation doesn't list subclasses

Finding superclasses of objects is easy - it is right at the top of the page. But it is not so simple to find subclasses. The mutable version of classes are often referenced to in an introductory paragraph, but other subclasses rarely are.

I don't know how people are supposed to find specialized subclasses of CALayer. What I did was search google for "Inherits from CALayer : NSObject site:apple.com" - there should be a better way. That was the only way I found out about a CAShapeLayer, CATiledLayer and a CAEmitterLayer. I really wish they had a list somewhere. I guess this is just a part of Apple not explaining overviews and concepts well.

The documentation doesn't give good examples

Often if you want to do something fairly simple, and are not sure how a class is used, the documentation doesn't help. After you know how to use a class, the documentation can teach you how to make it do more; but if you are not sure where to even use it, it won't tell you. Sometimes they will have a few examples which can help a lot, but stackoverflow is by far a better choice to learn from if you want a simple example. Once you know how to do basic things you can go back to the documentation to see what else you can do.

There are of course Apple example projects. My problem with them is that it is often hard to strike the right balance between doing too much - and making it hard to find the few lines which show how to do something. Or doing to little and having bad overall design. I don't know what the right balance is, but often I think that 20 lines of code are more useful than a sample project.

The documentation hides stuff

When reading the documentation a class often does much more than what is stated on the page which is explaining it. Full understanding of a Class requires reading many different pages and sometimes important information isn't on the page you expect it to be on.

Look in subclasses

Often much functionality is hidden in a class' superclass. This is true for all of the mutable versions of common class such as NSMutableString, NSMutableArray, and NSMutableDictionary. It is also true for some places where you won't expect it. To dismiss a keyboard from UITextView is 'resignfirstresponder' which is in UIResponder. If you want to know when a UITableView is scrolled you need to remember that it inherits from UIScrollView. And if you want to have a UIButton selected remember that it is a UIControl.

Look in protocols

Sometimes classes have a lot of their functionality hidden in the "conforms to" at the top of the documentation. If you want a UITextField to act like a password field you won't find it on the page for UITextField, but hidden in UITextInput. When doing a product request from the app store you set your SKProductsRequestDelegate, but you may know now that the protocol itself conforms to the protocol SKRequestDelegate.

Look for UI Category Additions

Sometimes there are other methods that aren't even listed in the top of the page. These are often UIKit addition to Foundation Framework classes (the classes that start NS). For example in iOS you can call sizeWithFont: on a NSString to figure out how big a string would be in a certain font, but you won't find it in NSString documentation. You would find it in NSString UIKit Additions Reference.

Similarly, there are category additions for NSBundle, NSIndexPath, NSCoder, and NSValue. In general when Apple wants a a foundation class to do some drawing, or something else relating to displaying on a screen it will make an Addition to it. Often these are referenced in the introductory paragraphs about the class, but it is easy to miss.

Look for external standards

Apple often follows industry standards, coding practices and guidelines. When they do they will rarely tell you any more than pointing to a RFC document. For example if you want to use NSString's stringWithFormat you will need to look up the IEEE printf specification (this is the same for NSLog statements). Likewise, if you want to know what NSURL means by "path" and "query" you won't see something simple and meaningful such as:
[scheme]://[net_loc]/[path];[params]?[query]#[fragment]
Instead all the documentation does is refer to RFC 1808 like some kind of mantra.

There are similar issues in NSLocale and NSDateFormatter. I understand where Apple is coming from; if you are following a standard you shouldn't have to repeat what the standards says. Still it is a big pain and something to watch out for.

The Documentation has almost identical documentation for Mac

I don't know why, but every time I search for Apple documentation in Google the mac documentation shows up, but not the iOS version. I need to manually change the URL to get the iOS version. Sometimes I forget to do this and look at the Mac version instead. Generally this is not a big deal. The biggest difference is when stuff was introduced and deprecated, which I want by iOS version not Mac version.

Sometimes there can be more significant (yet subtle) differences between the two documentations. For example, NSDateFormatter in the Mac has - (id)initWithDateFormat:(NSString *)format allowNaturalLanguage:(BOOL)flag while this initializer does not exist on iOS. Likewise - (BOOL)allowsNaturalLanguage does not exist on iOS while it does on Mac. It is just another thing to watch out for.