NEW: Learn SwiftUI with my free YouTube video series! >>

How to read Apple’s developer documentation

Paul Hudson       @twostraws

To many people this article will sound strange, because we’re used to the way Apple’s API documentation works and so we’re mentally tuned to finding what we want quickly.

But here’s a fun fact: one of the most popular article requests I had last year to help folks actually read Apple’s code documentation. How do you find the iOS APIs you’re looking for, how do you navigate through all the material to find what you actually want, and how do you dig deep to get an understanding of why things work the way they do?

So, if you’ve ever needed help to understand Apple’s developer documentation, first I want you to know that you’re not alone – many, many people struggle with it. But second, I hope this article will help: I’ll try my best to explain how it’s structured, what it’s good for (and not so good for), and how I use it.

More importantly, I’ll show you where experienced developers look for extra information that is often even more valuable than Apple’s online documentation.

“What is it?” vs “How do you use it?”

Any written API documentation usually takes one of five forms:

  1. Interface code that shows what something is: method names and parameter, property names and types, and similar, with a little text describing what it’s supposed to do.
  2. Text description of the API describing what it’s supposed to do as well as general guidance of use cases.
  3. Sample code that uses the API extensively to make something useful.
  4. Code snippets showing the basics of how to use an API.
  5. A cookbook solving common problems: how to do X, how to do Y, and how to do Z, and so on.

Very roughly, Apple does a lot of the first, a fair amount of the second and third, a small amount of the fourth, and almost none of the fifth.

So, if you’re looking for specific examples of “how to do X with Y” you’re better off starting with my Swift Knowledge Base – that’s exactly what it’s there for.

Understanding the problem Apple’s documentation is there to solve will help you get the most from it. It’s not trying to be a structured tutorial – it won’t introduce you to a series of concepts to help you achieve a goal – but instead is there to act as a reference guide for the thousands of APIs Apple supports.

Finding a class

Apple’s online documentation is at https://developer.apple.com/documentation/, and although you’re likely to have a local copy in Xcode most folks I speak to use the online version just because they can find things more easily.

The overwhelming majority of Apple’s documentation describes interfaces, and it’s what you’ll see most of the time. I want to work with a practical example, so please start by opening https://developer.apple.com/documentation/ in your web browser – that’s the homepage for all of Apple’s developer documentation.

You’ll see all of Apple’s APIs split up into categories like App Frameworks or Graphics and Games, and already you can see an important thing: all the text in dark blue is clickable, and will take you through to the API documentation for a specific framework. Yes, it uses the same font and size, it’s not underlined, and to be honest there’s not a whole lot of difference between dark blue links and black text, but you still do need to keep an eye out for those links – there are lots of them, and you’ll be using them a lot to dig deeper into topics.

For now please select UIKit from the App Frameworks category, and you’ll see a brief overview of what it does (creates user interfaces for iOS), a large yellow box marked “Important”, then a list of categories. Those yellow boxes really are worth paying attention to: although they are used frequently, they nearly always stop you making fundamental mistakes that cause weird problems later on.

What matters on this page is the list of categories that together describe UIKit. This is where folks usually get lost: they want to learn about something like UIImage, so they have to look through that list to find where it might fit.

In this case you might look under “Resource Management” because its subtitle of “manage the images, strings, storyboards, and nib files that you store outside your main executable” sounds promising. However, you’d be disappointed – you need to scroll way down to the Images and PDF section to find UIImage.

This is why most folks I’ve talked to just use their favorite search engine. They type in the class they care about, and - as long as it has a prefix like “UI”, “SK”, or similar – it’s likely to be the first result.

Don’t get me wrong: I know this approach isn’t ideal. But faced with either searching for a class or going to https://developer.apple.com/documentation/, selecting a framework, choosing a category, then selecting a class, the first is simply faster.

Important: whichever approach you choose you end up at the same place, so just do what works best for you. For now, please find and select UIImage.

Reading a class’s interface

Once you select the class you care about, the page has four main components: overview, version summary, interface, and relationships.

The overview is the “text description of the API describing what it’s supposed to do as well as general guidance of use cases” I mentioned earlier – I asked you to choose UIImage because it’s a good example of when that text description works well.

When it’s a class I’m using for the first time, particularly if it were only recently introduced, I’ll usually read the Overview text. But for everything else – any class I’ve used at least once before – I skip right past it and try to find the specifics of what I came for. Remember, Apple documentation really isn’t designed to be a learning tool: it works best when you come with a specific purpose in mind.

The version summary – the side bar on the right of the page – is really important if you don’t always develop for the latest version of your chosen Apple platform. In this case you’ll see iOS 2.0+, tvOS 9.0+, and watchOS 2.0+, which tells us when the UIImage class first available on those three operating systems, and also that it’s still available – if it were deprecated (no longer available) you’d see something like iOS 2.0-9.0.

The real content on this page – and on all pages that serve as the homepage for a specific class in Apple’s frameworks – is listed under the “Topics” heading. This will list all the properties and methods supported by the class, broken up again into categories of use: “Getting the Image Data”, “Getting the Image Size and Scale”, etc.

If the class you selected has any custom initializers, they should always be shown first. UIImage has a lot of custom initializers, and you’ll see them all listed as signatures – just the parts that describe parameters it expects. So, you’ll see things like this:

init?(named: String)
init(imageLiteralResourceName: String)

Tip: if you’re seeing Objective-C code, make sure you change your language to Swift. You can do this at the top-right of the page, which is also where you can enable the API changes option for the times when an important iOS beta introduces changes.

Remember, initializers that are written init? rather than init are failable – they return an optional so that they can send back nil if initialization failed.

Directly below the initializers you will sometimes see some methods for creating highly specialized instances of the class. These aren’t initializers in the Swift sense, but they do create instances of the class. For UIImage you’ll see things like this:

class func animatedImageNamed(String, duration: TimeInterval) -> UIImage?

The class func part means you’d call it as UIImage.animatedImageNamed()

After the initializers, things become a bit less organized: you’ll find properties methods, and enums mixed together freely. While you could just scroll through to find what you’re looking for, I think it’s safe to say most folks just Cmd+F to find some text on the page!

There are three things to watch out for:

  • Nested types – classes, structs, and enums – are listed alongside properties and methods, which takes a little getting used to. For example, UIImage contains the nested enum ResizingMode.
  • Anything with a line through it is deprecated. This means Apple intends to remove it at some point so you should not use it for future code, and start rewriting any existing code. (In practice, most APIs stay as “deprecated” for a long time – years and years.)
  • Some very complex classes – see UIViewController, for example – will have extra documentation pages mixed alongside their methods and properties. Look for the page icon next to them, plus a plain English title like “Positioning Content Relative to the Safe Area”.

At the bottom of the page you’ll find Relationships, which tells you which class it inherits from (in this case it comes straight from NSObject), as well as all the protocols it conforms to. This section is more helpful when you’re looking at Swift types, where the protocol relationships are more complex.

Reading a property or method page

You’ve chosen a framework and class, and now it’s time to look at a specific property or method. Find and select this method:

class func animatedResizableImageNamed(String, capInsets: UIEdgeInsets, resizingMode: UIImage.ResizingMode, duration: TimeInterval) -> UIImage?

You should find it in the Creating Specialized Image Objects category.

This isn’t a complicated method, but it does demonstrate the important parts of these pages:

  • Apple has a few different ways of writing method names. There’s the previous one – the long class func animatedResizableImageNamed – then the form shown in the title of the method page (animatedResizableImageNamed(_:capInsets:resizingMode:duration:)), and the form in the Declaration section of the method page.
  • As you can see in the version summary (on the right again) this method was introduced in iOS 6.0. So, while the main UIImage class has been around since day 1, this method was introduced a few years later.
  • The individual parts of the method declaration, all colored purple, are clickable. Be careful, though: if you click UIImage.ResizingMode where you’ll go depends on whether you clicked “UIImage” or “ResizingMode”. (Tip: you will usually want to click the one on the right.)
  • You’ll see a brief explanation of the meaning of each parameter and the return value.
  • The Discussion section details specific usage notes for this method. This is – nearly always – the most useful part of each page, because here is where you’ll see things like “Don’t call this method” or “Be careful when…”
  • You might find a See Also section, but this is a bit hit and miss – here it’s just the same listing of methods we had on the previous page.

Now, UIImage is an old class and it doesn’t change much, so its documentation is in a good state. But some newer APIs – and many older APIs that don’t get quite as much love as UIKit – remain poorly documented. For example, SCNAnimation from SceneKit, or UITextDragPreviewRenderer from UIKit: both were introduced in iOS 11, and both still contain “No overview available” as their documentation 18 months after they were announced.

When you see “No overview available” your heart will sink, but don’t give up just yet: let me show you what I do next…

Looking at the code

Even though Apple’s online documentation is pretty good, all too often you meet “No overview available”, or you find there just isn’t quite enough information to answer your question.

Conway’s Law states that organizations that design systems are constrained to produce designs which are copies of the communication structures of these organizations.” That is, if you work in a certain way, you’ll design things in a similar way.

Apple’s unique position in our industry causes them to work in a rather unusual way – it’s almost guaranteed to be entirely unlike the way your own company works. Yes, they have API review discussions where they try to thrash out how an API should look in both languages, and yes they have teams dedicated to making documentation and sample code.

But their threshold for getting sample code out is extremely high: usually something needs to be really good to get out, and to have passed multiple layers of checks for things like legal issues. So, whereas I can type up a project in an hour and put it live as an article straight away, it takes significantly longer for Apple to do the same – they take their image very seriously, and quite rightly. If you’ve ever wondered why articles appear on the official Swift blog so rarely, now you know!

Now, the reason I’m saying all this is that Apple has a shortcut that gets used a lot: the threshold for their engineers to leave comments in their code appears to be significantly lower, which means very often you’ll find valuable information right there in Xcode. These comments are like gold dust: they come straight from Apple’s developers rather than their developer publications team, and as much as I have deep love for devpubs it’s nice to hear straight from the, er, source.

Remember I mentioned SceneKit’s SCNAnimation is undocumented on Apple’s developer site? Well, let’s take a look at what Xcode can show us: press Shift+Cmd+O to bring up the Open Quickly menu, make sure the Swift icon on the right is colored in rather than hollow, then type “SCNAnimation”.

You’ll see a few options listed, but you’re looking for the one defined in SCNAnimation.h. If you’re ever not sure, choosing the file that is YourClassName.h is your best bet.

Anyway, if you open SCNAnimation.h Xcode will show you a generated version of the SCNAnimation header file. It’s generated because the original is Objective-C, so Xcode does a live translation of that for Swift – that’s what the colored-in Swift logo means in the Open Quickly box.

Now, if you press Cmd+F and search for “class SCNAnimation”, you’ll find this:

/**
 SCNAnimation represents an animation that targets a specific key path.
 */
@available(iOS 11.0, *)
open class SCNAnimation : NSObject, SCNAnimationProtocol, NSCopying, NSSecureCoding {  
    /*!
     Initializers
     */

    /**
     Loads and returns an animation loaded from the specified URL.

     @param animationUrl The url to load.
     */
    public /*not inherited*/ init(contentsOf animationUrl: URL)

And that’s just the start. Yes, the class and all its internals all have documentation, including usages notes, default values, and more. All this really ought to be in the online documentation, but for whatever reason it still isn’t, so be prepared to look up code as a helpful addition.

Last tips

At this point you should be able to look up the online documentation for any code you like, and look up the header file comments for extra usage notes.

However, there are two more things you need to know before you’re ready to face the full range of Apple documentation.

First, you will frequently come across documentation that is marked as being “archived”, “legacy”, or “retired” – even for things that are comparatively recent. When it’s really old you’ll see messages like “This document may not represent best practices for current development. Links to downloads and other resources may no longer be valid.”

Despite being one of the world’s largest companies, Apple’s engineering and devpubs teams are hardly overflowing with personnel – it just isn’t possible for them to keep everything updated while also covering new APIs. So, when you see “archived” documentation or similar, exercise your judgement: if it’s in some version of Swift at least you know it’s vaguely recent, but even if it isn’t you might still find there’s a lot of valuable information there.

Second, Apple has a handful of stand out documents that are particularly valuable. These are all listed in the footer of https://developer.apple.com, but the main one is the Human Interface Guidelines. This walks you through all parts of designing apps for Apple platforms in a cohesive flow, including pictures to illustrate key points, and providing lots of specific advice. Even though this document is the single most important one to think about when building iOS apps, surprisingly few developers seem to have read it!

Where next?

I’ve written previously about the problems with Apple’s documentation – I’m afraid there’s no encouragement there, but at least it might help you feel less alone if you’re struggling.

Fortunately, I have lots of material that might prove more useful:

What ways do you find most effective for reading Apple documentation? Send me your tips on Twitter: @twostraws.

LEARN SWIFTUI FOR FREE I wrote a massive, free SwiftUI tutorial collection, and also have a growing list of free SwiftUI tutorials on YouTube – get started today!

 

MASTER SWIFT NOW
Buy Testing Swift Buy Practical iOS 12 Buy Pro Swift Buy Swift Design Patterns Buy Swift Coding Challenges Buy Server-Side Swift (Vapor Edition) Buy Server-Side Swift (Kitura Edition) Buy Hacking with macOS Buy Advanced iOS Volume One Buy Advanced iOS Volume Two Buy Hacking with watchOS Buy Hacking with tvOS Buy Hacking with Swift Buy Dive Into SpriteKit Buy Swift in Sixty Seconds Buy Objective-C for Swift Developers Buy Beyond Code

About the author

Paul Hudson is the creator of Hacking with Swift, the most comprehensive series of Swift books in the world. He's also the editor of Swift Developer News, the maintainer of the Swift Knowledge Base, and Mario Kart world champion. OK, so that last part isn't true. If you're curious you can learn more here.

Was this page useful? Let me know!

Average rating: 4.9/5

Click here to visit the Hacking with Swift store >>