How to use Apple developer documentation
This information will teach you how to use Apple developer documentation efficiently and effectively.
You have learned that Objective-C and the Cocoa frameworks are designed (in part) to be largely self-documenting. However, as a beginner, and someone who is probably new to Objective-C, you’re not convinced yet. One of the information resources that will help convince you is the Apple developer documentation.
Should you buy a book that teaches you how to do iOS programming? Yes, probably. Which one? Well, it’s difficult to make recommendations that have relevance and accuracy over a period of time. Sorry. Visit a bookstore, and spend an hour or so browsing through the table of contents and foreword/introduction sections of a number of books. Pick one (or more) that you like.
Please note that even if you buy a book, you’ll still need to learn how to use the Apple developer documentation.
The goal of this document is to teach you how to use Apple developer documentation efficiently and effectively.
Where is the documentation?
Two places – online (Apple) and in Xcode. The online content is available through Xcode, so let’s just look at Xcode.
So, in Xcode, how do I use the documentation? Essentially, there are two ways to begin using the documentation:
- On its own, as a “library”
- When writing code, accessing code/context specific documentation
Documentation: On its own, as a “library”
In Xcode, on the Help menu, choose Developer Documentation.
Use navigation and/or the search field to help you locate the documentation you want. Be on the lookout for special features, including the ability to obtain/download the documentation in PDF form.
For more information, see the section below, titled “Using full-fidelity help”.
Documentation: When writing code, accessing code/context specific documentation
As a beginner, let’s assume that there are three major code elements that you will typically want help with:
- Class – its purpose, usage, and members
In Xcode, position the cursor on top of a class name, or a property name, or one of the parts of a method name. Then, right-click. The menu will offer you two documentation-specific choices:
- Jump to Definition
- Quick Help
In our first lecture, we learned about the application delegate. It is a class named similar to <appname>AppDelegate. It includes a number of methods, and you learned that the methods are defined either in the superclass (i.e. the base or parent class), or in a “protocol”.
Let’s assume that you wanted to learn more about any of these methods – where they are defined, their purpose, etc. Open <appname>AppDelegate.m. Scroll down, until this line of code comes into view:
Jump to Definition
Now, position the cursor on top of one of the parts of the method name. For example, click somewhere on the “application:” part.
Now, right-click, and choose Jump to Definition.
Xcode will “jump” to the code module that holds the definition for the method. In this example, it shows you UIApplication.h, the header for the UIApplication class.
Notice the window title; it displays “UIApplication.h”. Also, notice the method definition, with a light-blue background highlight.
Your initial conclusion is that the method is defined in the UIApplication class. That’s reasonable, but it isn’t correct in this situation. Often a “protocol” is defined in the same source code file as the class. Scroll up, and look for a protocol definition statement:
The lesson here is to look at the .h header file a bit more, to make sure you reach the right conclusion.
OK; great – we know where the method is defined – in the UIApplicationDelegate protocol. Tell me more…
Continuing from the previous section, right-click on a part of the method, and choose Quick Help. In the following image, “application:” was right-clicked:
The small panel/window shows “Quick Help” info. If that amount of help isn’t enough, look for the icon that looks like a book; it is in the upper-right area of the small panel/window. Click it, and the full-fidelity reference documentation window will open:
As an alternative to right-clicking the class, property, or method name, you can use these mouse-and-keyboard actions:
- Jump to Definition – Option + double click
- Quick Help – Command + double click
Can I access “Quick Help” directly?
Do we always have to do these two steps in sequence? Can we just get Quick Help (and then full-fidelity documentation) in one step?
Well, it depends. Typically for class names and property names, the answer is “yes”. Just right-click the name, and choose Quick Help (or Command+double click).
If you try this for methods that are defined in the superclass or in a protocol, the small panel/window will tell you “Documentation not found”:
If it does this, then back up, and “Jump to Definition” before you try “Quick Help”.
Using full-fidelity help
The full-window, full-fidelity documentation will be helpful, but only if you know how to use it efficiently and effectively.
Let’s look a sequence of five screen shots, which enable us to start at the documentation’s “home” page, search for a class reference document, and drill down to the detail we want.
Image 1 – the Apple Developer documentation “home” page
Image 2 – enter a search term
In the upper-right search field, enter a search term. In this example, we are looking for UIView, so we entered “uiview”.
The window updated as we typed. The left side shows a results list. The right side shows a reference document.
Image 3 – select what you want from the left-side results list
Click “UIView” from the left-side results list. Notice that it has a purple-colored square, with a letter C inside – this tells you that it is a “Class” reference document.
Notice that the right-side reference document updates to show us the UIView Class Reference.
Image 4 – close the results list
In the search field, in the upper-right of the window, clear the search term by clicking the “X” icon/circle.
The results list disappears, showing us the reference document.
Image 5 – learn how to use the document navigator, and the document contents
Almost all reference documents have the same layout and navigation structure. On the left-side document navigator, it shows a table of contents, with (typically) these sections:
- Class Methods
- Instance Methods
- Revision History
- Companion Guide(s) (if any)
Not all reference documents have all sections. You can use the triangle-shaped expand/collapse icons to show and hide the sub-sections. Then, click on any section name to re-position the content.
Apple “Competencies” documentation
Apple has created a set of very readable documents to help you get started with Cocoa and iOS development. Highly recommended.