The Documentation Window

There are two main categories of documentation provided by Apple:

Primary documentation

The primary documentation (reference documentation) for Cocoa classes and other symbols is included entirely within Xcode, and is displayed in the documentation window (Window → Developer Documentation or Help → Developer Documentation, Command-Shift-0). You can also view the same documentation online, at https://developer.apple.com/documentation.

Secondary documentation

Secondary documentation consisting of older guides, sample code, and technical notes and Q&As is available only online, at https://developer.apple.com/library/archive/navigation. Apple refers to this material as the documentation archive.

Within the documentation window, the primary pathway is a search; press Command-Shift-0 (or Command-L or Command-Shift-F if you’re already in the documentation window) and type a search term, typically a class name such as “NSString” or “UIButton.” As you type, you’re shown the top search results pertinent to the language of your choice (such as Swift or Objective-C). You can choose a result with the mouse, or you can navigate the results with arrow keys and press Return to select the desired hit.

You can also perform a documentation window search starting from within your code. You’ll very often want to do this: you’re looking directly at a symbol (a type name, a function name, a property name, and so on) at its point of use in your code, and you want to know more about it. Select text in your code (or anywhere else) and choose Help → Search Documentation for Selected Text (Command-Option-Control-/). This is like typing that text into the search field in the documentation window.

The documentation window behaves basically as a sort of web browser. Terms shown in a documentation page are links; click one to navigate to the documentation page about that term. You can then navigate between pages you’ve already loaded, using Navigate → Go Back and Navigate → Go Forward (or the back and forward buttons in the documentation window). To split your view of the documentation into multiple tabs, choose File → New → Window Tab (Command-T); to open a link in a new tab, hold Command when you click the link.

A hierarchical table of contents for the whole documentation appears in the navigator pane at the left of the documentation window; to see it if it isn’t showing, choose View → Navigators → Show Navigator (Command-0), or click the Navigator button in the window toolbar. The table of contents can display any of three panes: Swift, Objective-C, or Other. You can switch between them with the pop-up menu at the top of the table of contents, or use the keyboard shortcuts (Command-1 and so on). To select in the table of contents the page you’re currently viewing, choose Editor → Reveal in Navigator (or use the contextual menu).

To search for text within the current documentation page, use the Find menu commands. Find → Find (Command-F) summons a find bar, as in Safari.

Class Documentation Pages

When dealing with Cocoa, your target documentation page will most likely be the documentation for a class, such as the page shown in Figure 8-1. Here are some typical features of a class documentation page:

Figure 8-1. The start of the UIButton class documentation page

Jump bar

At the top of the page is the jump bar. This has two main purposes:

Breadcrumbs

The jump bar functions as a kind of “breadcrumbs” display of where you are. The UIButton class documentation page is in the Views and Controls section of the UIKit division of the documentation. This is the same hierarchy in which the page is displayed in the navigator table of contents.

Navigation

Each item in the jump bar is a hierarchical menu, displaying the same hierarchy as in the navigator table of contents. Choose a menu item to navigate there. As with the Xcode project window editor’s jump bar, you can type to filter the items of the currently selected menu.

Language

Links let you choose between Swift and Objective-C as the language for display of symbol names.

Availability

This list tells you two important things:

• What sort of hardware you’re programming for when you use this class. That’s important because searches are not filtered by hardware type. If you were to stumble accidentally into the NSViewController class documentation page, you might be confused about how this class fits into the rest of iOS programming, unless you notice that iOS is not listed in this class’s Availability.

• The lowest version number in which this class became available. The UIGraphicsImageRenderer page, for example, tells you that this class is available in iOS 10.0 and later. So you wouldn’t be able to use it in code intended to run on iOS 9.

Framework

The framework that vends this class.

On This Page

The class reference page is divided into sections, and these are links to them, in order:

Declaration

The formal declaration for this class, showing its superclass.

Overview

If a page has an Overview section, read it! It explains what this class is for and how to use it. It may also contain valuable links to guides that provide related information.

Topics

These are primarily the class’s members — its properties and methods — grouped by their purpose. Each member is accompanied by a short description; click the member itself to see further details. (I’ll talk more about that in a moment.) There may also be listings for enums used by this class’s properties and methods, and notifications if this class emits any; the UIApplication class documentation page is a case in point.

Relationships

There are two chief kinds of relationship that a class can have, and you’ll want to keep an eye on both of them; a common beginner mistake is failing to follow the documentation links in this section:

Inherits from

This class’s superclass. A class inherits from its superclasses, so the functionality or information you’re looking for may be in a superclass. You won’t find addTarget(_:action:for:) listed in the UIButton class page; it’s in the UIControl class page (UIButton’s superclass). You won’t find out that a UIButton has a frame property from the UIButton class page; that information is in the UIView class page (UIControl’s superclass).

Conforms to

Protocols adopted by this class. Again, the functionality or information you’re looking for might be documented for a protocol rather than in this class’s own page. For instance, you won’t discover the viewWillTransition(to:with:) method on the UIViewController class page; you have to look in the documentation for the UIContentContainer protocol, which UIViewController adopts.

When you click the name of a property or method in a class documentation page, you’re taken to a separate page that describes it in detail. This page is laid out similarly to a class documentation page:

Jump bar

The jump bar provides breadcrumb navigation leading back to the class documentation page.

Language

The page gives you a choice of languages.

Availability

The availability for a property or method need not be the same as its class’s availability, because a class can acquire (and lose) members over time. The UINavigationBar class is as old as iOS itself and is available starting in iOS 2.0, but the prefersLargeTitles property didn’t appear until iOS 11.0.

On This Page

There is no separate Overview section, but there is always an initial summary of purpose (the same summary that appears on the class documentation page). The other sections of a method’s page are:

Declaration

The formal declaration for this method, showing its parameters and return type.

Parameters

Separate explanations for each parameter.

Return Value

An explicit description of what this method returns.

Discussion

Often contains extremely important further details about how this method behaves. Always pay attention to this section!

See Also

Links to related methods and properties. Helpful for getting a larger perspective on how this method fits into the overall behavior of this class.

The Topics section of a class documentation page may list many class members, and these can rapidly threaten to become overwhelming. If you know the name of a class member that you’re interested in, or you want to get to a particular topic quickly, how are you going to reach it without the tedium of scrolling? Don’t forget the jump bar! The jump bar lists all the class members listed on the page, grouped by topic. And that list can be filtered by typing. Let’s say I know that the class member I’m interested in contains the term “background.” I summon the rightmost level of the jump bar, type “ba,” and am shown a shortened list of just those terms (Figure 8-2). Now it’s easy to navigate to the detail page for any of those items.

Figure 8-2. Filtering the jump bar for the UIButton topics

In addition to the class documentation, the built-in primary documentation includes explanatory guides on overall topics. The existence of these guides is not always obvious. The UIButton class documentation is inside the Views and Controls section; that page, the section page, is an introductory guide to views and controls. Sometimes there are extensive explanatory pages, effectively constituting the chapters of a virtual booklet. The Table of Contents can be a big help in spotting these; such pages are marked with a document icon. The discussion of Swift Packages is a case in point.

Quick Help

Quick Help is a condensed rendering of the documentation for a particular symbol such as a type, function, or property name. It appears with regard to the current selection or insertion point automatically in the Quick Help inspector (Command-Option-3) if the inspector is showing. For instance, if you’re editing code and the insertion point or selection is within the term viewDidLoad, documentation for the viewDidLoad method automatically appears in the Quick Help inspector if it is visible. Quick Help is also available in the Quick Help inspector for interface objects selected in the nib editor.

Quick Help documentation can also be displayed as a popover window. Select a term in the code editor and choose Help → Show Quick Help for Selected Item (Command-Control-Shift-?). Alternatively, hold Option and hover the mouse over a term until the cursor becomes a question mark; then Option-click the term.

The Quick Help documentation contains links. Click the Open in Developer Reference link to see the full documentation in the documentation window.

You can inject documentation for your own code into Quick Help. To do so, precede a declaration with a comment enclosed in /**...*/ or a sequence of single-line comments starting with ///. Within the comment, Markdown formatting can be used (http://daringfireball.net/projects/markdown/syntax). The first paragraph of the comment becomes the Summary field for Quick Help; remaining paragraphs become the Description field, except that certain list items (paragraphs beginning with * or - followed by space) are treated in a special way, such as:

• List paragraphs beginning with Parameter paramname: are incorporated into the Parameters field.

• A list paragraph beginning with Throws: becomes the Throws field.

• A list paragraph beginning with Returns: becomes the Returns field.

• A list paragraph beginning with Note: becomes a Note field.

Here’s a function declaration with a preceding comment:

/**
Many people would like to dog their cats. So it is *perfectly*
reasonable to supply a convenience method to do so:

* Because it's cool.
* Because it's there.

* Parameter cats: A string containing cats

* Returns: A string containing dogs
*/

func dogMyCats(_ cats:String) -> String {
    return "Dogs"
}

The double asterisk in the opening comment delimiter denotes that this is documentation, which is automatically associated with the dogMyCats method declaration that follows it. The outcome is that when dogMyCats is selected anywhere in my code, its documentation is displayed in Quick Help (Figure 8-3). The first paragraph of the comment becomes the Summary, and is also displayed as part of code completion (see Chapter 9). The word surrounded by asterisks is formatted as italics; the asterisked paragraphs become bulleted paragraphs; and the last two paragraphs become special fields.

Figure 8-3. Custom documentation injected into Quick Help

You can also generate a documentation comment automatically. Select within the declaration line and choose Editor → Structure → Add Documentation. The comment is inserted before the declaration. The description, plus (if this is a function declaration) the Parameters, Returns, and Throws fields, as applicable, are provided as placeholders.

There are additional special documentation fields. For more information about these, see the “Markup Functionality” page of Apple’s Markup Formatting Reference.

Symbol Declarations

A symbol is a declared term, such as the name of a function, variable, or object type. If you can see the name of a symbol in the code editor, you can jump quickly to the declaration of that symbol. Select the term and choose Navigate → Jump to Definition (Command-Control-J); alternatively, hold Command-Control and hover the mouse over a prospective term, until the cursor becomes a pointing finger, and then Command-Control-click the term:

• If the symbol is declared in your code, you jump to its declaration in your code; this can be helpful not only for understanding your code but also for navigation.

• If the symbol is declared in the Swift library or a Cocoa framework, you jump to its declaration in the header file. (I’ll talk more about header files in the next section.)

To jump to the declaration of a symbol whose name you know, even if you don’t see the name in the code before you, choose File → Open Quickly (Command-Shift-O). A search field appears. In it, type key letters from the name, which will be interpreted intelligently; to search for application(_:didFinishLaunchingWithOptions:), you might type “appdidf.” Possible matches are shown in a scrolling list below the search field; you can navigate this list with the mouse or by keyboard alone. Besides declarations from the framework headers, declarations in your own code are listed as well, so this, too, can be a rapid way of navigating your code.

In addition, a list of available symbols appears in the Symbol navigator (Chapter 6). If the second icon in the filter bar is highlighted, these are symbols declared in your project; if not, symbols from imported frameworks are listed as well. Click to navigate to a symbol declaration.

Header Files

A header file can be a useful form of documentation. The header is necessarily accurate, up-to-date, and complete, and it may contain comments telling you things that the documentation doesn’t. Also, a single header file can contain declarations for multiple classes and protocols. So it can be an excellent quick reference.

The previous section describes various ways of jumping to a symbol declaration; since most symbols are declared in header files, these are ways of reaching header files. To reach NSString.h, select the term NSString wherever it may appear in your code and jump to its declaration, or choose File → Open Quickly (Command-Shift-O) and type “NSString.” Once you’re in a header file, you can navigate it conveniently through the jump bar at the top of the editor.

When you jump to a header file from your code, the header file, if it is written in Objective-C, can appear in Objective-C or Swift:

• To switch from an Objective-C original to its Swift translation, choose Generated Interface from the Related Items menu (at the left end of the jump bar, Control-1).

• To switch from a Swift translated (generated) header to the Objective-C original, choose Navigate → Jump to Original Source, or choose Original Source from the Related Items menu.

You can learn a lot about the Swift language and the built-in library functions by examining the Swift header file. The special Swift header files for Core Graphics and Foundation are also likely to prove useful. A neat trick is to write an import statement just so that you can reach the corresponding header. If you import Swift at the top of a Swift file, the word Swift itself is a symbol that you can use to jump to the Swift header.

Sample Code

The documentation archive includes plenty of sample code projects. You can view the code in a browser, but you can see only one file at a time, so it’s difficult to get an overview. Instead, click the Download Sample Code button and open the downloaded project in Xcode; with the sample code project open in a project window, you can read the code, navigate it, edit it, and of course run the project.

Some of the primary documentation guides contain links to downloadable sample code as well. This sample code can be difficult to discover. In a few cases, the documentation archive links to it. In other cases, you just have to stumble across it. Again, the table of contents in the documentation window can be a big help here; sample code pages are marked with a curly braces icon.

As a form of documentation, sample code is both good and bad. It can be a superb source of working code that you can often copy and paste and use with very little alteration in your own projects. It is usually heavily commented, because the Apple folks are aware, as they write the code, that it is intended for instructional purposes. Sample code also illustrates concepts that users have difficulty extracting from the documentation. But the logic of a project is often spread over multiple files, and nothing is more difficult to understand than someone else’s code (except, perhaps, your own code). Moreover, what learners most need is not the fait accompli of a fully written project but the reasoning process that constructed the project, which no amount of commentary can provide.

Apple’s sample code is generally thoughtful and instructive, and is definitely a major component of the documentation; it deserves more appreciation and usage than it seems to get. But it is most useful, I think, after you’ve reached a certain level of competence and comfort. Also, while some of the sample code is astoundingly well-written, some of it is a bit careless or even downright faulty.

Internet Resources

Programming has become a lot easier since the internet came along and Google started indexing it. It’s amazing what you can learn with a Google search. Your problem is very likely one that someone else has faced, solved, and written about on the internet. Often you’ll find sample code that you can paste into your project and adapt.

Apple’s own online resources go beyond the formal documentation. There are WWDC videos (https://developer.apple.com/videos) from the current and previous years. Apple also hosts developer forums (https://forums.developer.apple.com); some interesting discussions take place in these forums, and they are patrolled by some very helpful Apple employees.

Other online resources have sprung up spontaneously as iOS programming has become more popular, and lots of iOS and Cocoa programmers post tutorials or blog about their experiences. Stack Overflow (http://www.stackoverflow.com) is a site that I’m particularly fond of; it’s a general programming question-and-answer site, not devoted exclusively to iOS programming, but with lots of iOS programmers hanging out there; questions are answered succinctly and correctly, and the interface lets you focus on the right answer quickly and easily.