What's Up, Docs? Find the Right Xcode Documentation, Exactly When You Need It
For iOS developers, Apple-supplied documentation provides crucial development support, but many developers don’t easily discover the full extent of help available both within Xcode and online at Apple’s developer website. In this write-up, I survey some of the most important documentation resources. I also provide access tricks for expanding the way you interact with these features.
Xcode Documentation and API Reference
In the latest version of Xcode, you open its documentation browser by pressing Command-Shift-0 (zero) or selecting the browser via Xcode’s Window menu (see Figure 1). This is a nicely positive change from the old-style command sequence of Command-Shift-Option-? (question mark). The new keyboard chord offers documentation the prominence it deserves for both easy recall and quick access.
Figure 1 Xcode’s Window menu.
Figure 2 presents the documentation window. This window includes a primary search bar at the top of the screen, with an action button just to its right. Use the search bar to look up elements; for example, you might search for SKNode to retrieve the class definition for Sprite Kit nodes.
Figure 2 Documentation and API reference.
As you type, Xcode shows the closest matches to your entered text. Select one from the pop-up list of most likely matches, or scroll to the bottom of the pop-up list and choose Show All Results for a more comprehensive list.
The action button at upper right enables you to redirect the documentation content to Safari, add bookmarks for commonly used pages, and more. Opening a page in Safari links to the local version of the document, producing a link to a file:// stored in your downloaded documentation sets.
Just to the left of the search bar is an outline button, which hides or shows the table of contents shown at bottom left in Figure 2. Click any item in this outline to jump to its corresponding section in the currently displayed documentation.
Choosing Find > Find (Command-F) opens a secondary search bar, shown in Figure 2 just below the main gray toolbar. Here you can enter text to search within the selected documentation, in order to find relevant parts of the document. Both the primary and secondary search bars provide buttons labeled with angle brackets (< and >), offering access to search histories. Find these buttons at the upper left in the toolbar for the primary search and at the right in the secondary search. Click the left angle bracket (<) to move backward through each history, and click the right angle bracket (>) to move forward.
The primary history buttons also allow you to click-and-hold either bracket to view an overview of the topics you have browsed. By selecting any of the displayed items from the pop-up (see Figure 3), you jump directly to that documentation.
Figure 3 History browser.
Each search field contains a small magnifying glass, which enables you to customize your search. With the pop-up for the primary search field (see Figure 4), specify which documentation sets you want to search. Choose All SDKs to return results from all installed options. For developers who work with multiple SDKs, this feature provides a way to focus searches and eliminate many irrelevant results.
Figure 4 Specify the documentation sets you want to search.
The pop-up for the secondary search field provides a list of recent search items (see Figure 5) where you can review recent searches and return to them with a simple click. The angle-bracket history buttons for this field navigate through each find request. If you use Find > Find Next (Command-G) or Find > Find Previous (Command-Shift-G), the bracket buttons move you through each “hit.” The items listed in Figure 5 represent individual searches, moving at a higher level of granularity than the buttons.
Figure 5 Recent searches.
- The Match Case option limits searches to exact lower- or uppercase searching. For example, when Match Case is enabled, Parent does not match parent, and vice versa. This feature helps when searching for API items, for example, as Apple’s camel-case conventions won’t match the parent property to the setParent: setter method.
The Wrap option, when enabled, loops to the top of the document when you hit the bottom of the file. (Thanks, Mike Glass!)
Figure 6 Find options.
In Figure 7, notice the left-pointing triangle within a square in the toolbar to the left of the outline button. This button hides/shows the documentation navigator, which consists of two tabs:
- The library tab provides an outline of all the materials available within the documentation browser, grouped by subject. Contents include sample code, guides, class references, and subtopic folders (such as 2D drawing and 3D drawing), each of which offers its own samples and references.
The bookmarks tab (to the right of the library tab) stores any item you have bookmarked using the Add Bookmark action (shown earlier in Figure 2).
Figure 7 The documentation navigator.