How to use Apple’s developer documentation

Why should you be able to work with Apple’s developer documentation

Have you wondered how to read Apple’s developer documentation? Being able to work with the official documentation has many benefits:

• know where to find the API you are looking for
• know how to look for features in an API that are uncommon in most tutorials
• be ahead of the curve, because you can read the most up to date reference guide in the Apple ecosystem
• work with outdated code examples and adapt to new features
• get a deeper understanding than what Youtube or other tutorials can teach you
• be able to adapt to changes made by Apple quickly

What the developer documentation is not

It is important to understand that the official documentation is not a good place to learn development in the Apple ecosystem from scratch. It is a reference guide that can help you to find the APIs and tools you need. There are hardly any coding examples or full guides on how to implement a feature in a step-by-step way.

I find it best to start with a small tutorial that gives me an introduction to the topic. For most APIs, you can find very good resources. In order to adapt the tool to my needs, I will go through the corresponding pages in the documentation. I am looking for ways to create and modify the tool.

Important note: In order to take advantage of the documentation, you need to have a solid understanding of the Swift / Objective-C programming language. The documentation is written in a way that mirrors the way the programming language works. Examples for what language specifics you might encounter are:

• initializers including failable inits and default values – how do you create the feature
• object-orientated programming with class inheritance: a UIButton inherited from UIControl which has e.g. target/action pattern implementation
• properties of a tool to customize and modify
• Delegate pattern to customize the behavior of a tool: e.g. UITableViewDelegate  with func tableView(UITableView, heightForRowAt: IndexPath)
• protocol-oriented programming: SwiftUI uses the View protocol

The primary source for Swift is https://swift.org/documentation/#the-swift-programming-language. 

Another important resource is the human interface guidelines.: https://developer.apple.com/design/human-interface-guidelines/

Navigation and Search tools

You can use the search tool on the top. The results show you also the corresponding framework.  The naming convention for the various APIs uses a prefix. If you are looking for an error in HealthKit this will be HKError, in MapKit it will start with MK and in StoreKit it will start with SK. This naming convention makes it easy to see directly which framework this feature belongs to.

You can use the search tool on the top. The results show you also the corresponding framework.  The naming convention for the various APIs uses a prefix. If you are looking for an error in HealthKit this will be HKError, in MapKit it will start with MK and in StoreKit it will start with SK. This naming convention makes it easy to see directly which framework this feature belongs to.

Page structure and search

The main page structure consists of 4 main areas. You have the declaration, the overview, topics, and relationships. If you work with this tool for the first time it is a good idea to spend some time reading the overview area.

The topics area will give you all the concrete code details. I usually start by looking for initializers because I see how I can create this specific tool. You can see different areas that will tell you how to customize the tool and more information about them too. In the case of a UISwitch, you can find out if the switch is on if you look at the isOn property of the switch. Some properties are enums. In order to know what this property will do, I usually click on the enum to see the different cases. The names are chosen in a way that they are the most self-explanatory.

On the right-hand side of the page, you can switch between Swift and Objective-C. You can see which framework this belongs to. We already saw that the prefix UI tells us that this view belongs to UIKit. There are also some fast navigation buttons that bring you directly to the section.

Most importantly is the availability. This tells you for which platform the feature is available. A UISwitch can be used for iOS and Mac Catalyst. If you look at a Switch in SwiftUI you will see more platforms. We can also see which versions are supported and if a feature is decrepitated.

If you use cmd + F, you can use the on-page search. This is useful if the page is very long or you already know the name you are looking for.

My final advice is to start reading through the documentation. It takes some time to get used to the navigation. But as you get better at understanding Swift and the way it is used in the frameworks, you will get increasingly faster in finding what you are looking for.