WHAT'S IN THIS CHAPTER?
Browsing the Xcode, API, and developer documentation
Searching for symbols, topics, and keywords
Navigating help documentation
Learning handy help shortcuts
Using quick help to get fast answers
Installing new documentation sets and keep them up to date
Modern operating systems are staggering in their size and complexity. The sheer quantity of application program interfaces (APIs) available to a developer can be overwhelming at times. There are scores of frameworks and libraries, each consisting of literally thousands of classes, methods, functions, and constants. Often, just finding the correct method or constant can be your most difficult programming task.
To help you navigate this jungle of symbols, Xcode provides integrated help and documentation. You can browse and search developer documentation. All of the major APIs are indexed, allowing you to call up the documentation for any symbol almost instantly.
This chapter gives you an overview of what help resources are available, shows you how to navigate the documentation, and explores a number of different search techniques.
A lot of the documentation features are nice to know but aren't critical for day-to-day development. If you want just the essentials from this chapter, read the following sections:
Navigating Documentation
Searching Documentation
Documentation Shortcuts
The documentation provided with Xcode, along with additional material available through subscription, include:
API Reference Documents
Technology Guides
Developer Articles
Technical Notes and Q&As
Release Notes
Sample Code
While programming, you're most likely to be using the API reference documents. These are the documents that describe the details of each individual class, method, function, and constant. You'll normally find these by searching or using one of the documentation shortcuts.
When you're just getting started or learning a new technology, the guides and articles are the best place to begin. Find these by browsing the documentation sets.
You can also browse the documentation sets for technical notes, release notes, and technical Q&As, but you're more likely to find them when searching or through a link from another article.
Xcode used to include numerous sample projects as part of the Xcode tools installation. Now, those sample projects — and many more — have references in the documentation sets, but the actual project code must be downloaded. See the "Sample Projects" section later in this chapter.
The main interface for all Xcode help is the Help and Documentation window, shown in Figure 12-1, which this chapter refers to simply as the help window. You have various ways of opening it, but the simplest is to choose the Help
Note
If you've used the help window in earlier versions of Xcode, you may find the new one somewhat perplexing. It's actually a substantial improvement and has a pleasantly simplified interface.
The help window, shown in Figure 12-1, has three basic parts. At the top is the help window's toolbar. It contains some essential controls, so make sure it's visible or your interactions with the help window will be extremely limited. The main pane that occupies most of the lower-right portion of the window is the documentation browser. It's a WebKit view and acts much like any standard web browser.
The search control bar underneath the toolbar, and the search results sidebar to the left, appear only when you are searching the documentation. The help window has two basic modes: browse only and search. When you enter any search term into the toolbar search field, the search control bar and search results sidebar appear. Clear the search term and they disappear again.
There's a special search tool for looking up the "man" (manual) pages that are part of the BSD operating system. It has its own command and toolbar control (see Figure 12-2). Man page searches are described in the "Man Pages" section, later in this chapter.
It's possible to create more than one help window by opening a link in a new Xcode help window. See the section "External Links" to learn how.
The easiest way to use the help window is as a browser. Like any browser, you need a place to start and Xcode provides several:
Most of the Help menu items load preset documentation pages
The "Home" page for each of the documentation sets
Bookmarks
Help
Each documentation set you install — see the "Managing Subscriptions" section later in this chapter — appears in the toolbar's Home pop-up menu, as shown in Figure 12-2.
If you want to explore the documentation of a particular operating system or technology, start at its home page. Over the years, most of the articles, technical notes, and other introductory material available from Apple's developer web site has migrated into the Xcode documentation sets — in much the same form.
Bookmarks are described later in the "Bookmarks" section.
As mentioned, the documentation browser is essentially a web page browser, so all of the standard elements (links, images, embedded video, scrolling) all work exactly as you would expect. The help window only adds two features to the browser: history and bookmarks. The back (Command+[) and forward (Command+]) history buttons are in the toolbar and act as you would expect them to. All other navigation is provided by the content of the documentation pages themselves — mostly via HTML and JavaScript. Thus, the organization and navigation of pages changes depending on the kind of documents at which you're looking, and can evolve as the documentation content is updated.
As of this writing, there are a couple of consistent themes. The document home pages or collection pages, as was shown in Figure 12-2, tend to list related documents and often have a table of contents on the left that let you jump to different sections. Some even have search, filter, and sorting features, like that shown in Figure 12-3.
The API documentation, as shown in Figure 12-4, adds a number of navigation tools. The navigation bar across the top lets you toggle the table of contents for the group of documents. The table of contents contains links that jump to various sections and related documents. It often contains high-level section titles that can be individually expanded or collapsed.
The pop-up navigation menu, also shown in Figure 12-4, lets you jump directly to various sections within the page and is organized very much like the functions menu in the text editor. Finally, the Previous and Next links at the upper-right link to the previous and next page within that document section; these are not history navigation buttons. When reading multi-page articles, use them to move sequentially through the material.
Choose the Find
Choose a bookmark from the Bookmark menu to revisit that document.
To manage your bookmarks, choose the Manage Bookmarks command in the Bookmarks toolbar control. In the bookmarks dialog box, shown in Figure 12-6, you can:
Remove a bookmark with the
-button.Add a bookmark to the current page with the + button.
Reorder bookmarks by dragging.
Rename a bookmark title by double-clicking.
Documentation pages may contain links to external sources (outside the /Developer/Documentation folder). These include:
Links to supplementary documents on Apple's web site
The PDF version of a document
Feedback and bug reporting links
Links to related standards (ISO, W3C, and so on)
File archives (ZIP files, disk images, and so on)
Multimedia (iTunes University, and so on)
Most external links are handed off to your operating system and are handled according to your system preferences; an HTML link will most likely open in your default browser, a file link may download the file to your Downloads folder, a PDF link may download the document and open it using the Preview application, and a podcast may launch iTunes.
A number of contextual commands are accessible by Control/Right-clicking a link or selection, as shown on the left in Figure 12-7, or anywhere else in a page, as shown on the right.
These commands are:
COMMAND | ACTION |
|---|---|
Open Link | Same as clicking the link |
Open Link in New Window | Creates a second Xcode help window with the contents of the link |
Copy Link | Copies the URL of the link to the clipboard |
Open Link in Browser | Sends the URL of the link to your default browser |
Find Text in Documentation | Enters the link or selected text as the search term (see the "Searching Documentation" section later in this chapter) |
Open Page in New Window | Creates a second Xcode help window with the same content |
Open Page in Browser | Sends the URL of the current page to your default browser |
The "in New Window" commands are the only way of creating multiple help windows. The original help window remains the principal help window for your project; shortcuts, for example, are always directed to the principal help window.
Opening a link or page in your browser is a great way of keeping multiple documentation pages open at once. Modern browsers, with their tabs and workspace sets, can be much more effective at organizing, remembering, and managing multiple help documents than the simple Xcode help window.
A special kind of external link is found in sample project pages. Recently, the Xcode developer tools suite has moved away from providing sample projects as part of the installation to providing links to sample projects in the documentation, going so far as to cross-reference each API with the example projects that use it. Figure 12-8 shows the ButtonMadness sample project page. I got to this page from the insertMenu:atIndex: method reference document.
You have two ways of exploring a sample project. The first is simply to view the source files in the help window using the pop-up menu, also shown in Figure 12-8.
The other method is to click the Open Project in Xcode button. You'll be prompted for a location on your disk. Choose a location and Xcode downloads the project archive to the selected folder, extracts the project files, and opens the project. If it did anything more for you, you'd be obligated to tip it afterwards.
Browsing the ADC documentation is great way to get an overview of a technology or work through a tutorial. During actual development, however, you usually just want to find something specific — and you want to find it in a hurry. The simplest way is to enter a search term into the search field.
The help window's search field is in the toolbar, as shown in Figure 12-9. Entering anything into the search field activates the help window's search mode and adds two additional sets of controls.
The search control bar appears underneath the toolbar and a search results sidebar appears on the left of the content area. These controls let you refine the search and browse its results.
Your search term is instantly and simultaneously used to search the documentation in three ways:
The results of each search appear in its own group in the search results sidebar. Each group always shows the most likely matches. If there are more, you can expand the results list by clicking one of the Show More Results buttons.
The API symbols group only searches the Application Programming Interface index of the documentation. These are the class, method, function, variable, and constant names documented in the API reference material. If you're looking for some specific framework or symbol, this is where you are mostly like to find it.
The article title and text groups search the titles and complete text of every article, technical note, guide, and reference page for a match. If you are trying to find a description of a particular technology or topic, these are the search groups you are most likely to find it in.
A search term can contain multiple keywords and operators. The search field recognizes the following operators:
OPERATOR | MEANING |
|---|---|
Logical group. Treats the terms between the parentheses as a single term. | |
| Not. Inverts the sense of the search term. |
| And. Requires that the term on the left and right are both found. This is the default when you're searching for multiple keywords. |
| Or. Matches if either the term on the right or the term on the left is found. |
| Required word. Equivalent to just searching for a keyword. |
| Unwanted word. Excludes any results that contain that keyword. |
| Wildcard. Creates a keyword that matches a partial word (for example, |
For example, the following search term locates all articles that contain the word "services," and either the word "sync" or "system," but do not contain the word "audio":
(sync | system) services -audio
Note
Every symbol in the API index is considered to be a single word. No multi--keyword search will ever match an API symbol, even if the symbol contains all of the keywords.
Clearing the search field hides the search control bar and the results sidebar again.
The search control bar further refines how the search keywords are applied, and the scope of what's searched. The search control bar has three controls, all shown in Figure 12-9.
The word boundary control determines how each search keyword must match a symbol or word in the documentation:
WORD BOUNDARY SETTING | MATCH RULE |
|---|---|
Contains | Keyword can appear anywhere in the word |
Prefix | Keyword must match the beginning of the word |
Exact | Keyword must match the whole word |
The prefix setting is most useful when searching the API reference documents for symbols. It allows you to type the beginning of a known symbol and quickly narrow down the list of symbols you're looking for. Contains and Exact apply equally to API and text searches.
Note
The wildcard operator may defeat or interact with the word boundary setting. For example, searching for menu* using the Exact setting is the same as -searching for menu with the Prefix setting.
You can limit which sets of documentation Xcode searches by selecting them in the Doc Sets control, shown in Figure 12-10.
Select only the platforms or technologies that you're using for development right now. That limits the scope of your searches to just the documentation that's appropriate for your development. If you are doing cross development that targets several versions of an operating system, you might also want to uncheck the modern documentation sets. That way, you're unlikely to accidentally use an API that only exists in the more recent OS.
The language sets control, shown in Figure 12-11, further limits your API symbol searches to only those symbols defined in the selected languages. For example, if you're programming in Objective-C, check C and Objective-C. If you're programming in JavaScript, uncheck everything except JavaScript. If you're programming in Objective-C++, you may want to check C, C++, and Objective-C.
The help document browser includes a simplified text search tool, very much like the single file search tool described in Chapter 8, for searching through the text of the current document. Press Command+F to reveal the search tool, as shown in Figure 12-12.
The document search tool has no options, but responds to the same Find Next (Command+G) and Find Previous (Shift+Command+G) commands that the single file search tool does. Click the Done button to dismiss the tool.
To find a command or a particular Xcode help topic, enter a term directly into the help menu's search field, as shown in Figure 12-13.
In Figure 12-13, the keyword "breakpoint" finds several Xcode commands and a variety of help documents. Hovering over one of the commands results reveals that command in the menu structure so that you can find it again in the future.
This is a great way to find menu commands. There are a lot of commands in the Xcode menus, and it's easy to lose track of where they are. Also, it seems that every new release of Xcode moves or renames about a third of the commands, so even seasoned Xcoders need to reorient themselves from time to time.
The lower portion of the menu lists the Xcode help document topics that match the search term. These open the help window to a specific Xcode help document.
Finally, the Search in Documentation Window command at the very bottom of the menu opens the help window and performs the same search, for those times where you don't find what you're looking for in the menu.
A number of shortcuts are available for accessing the help window and for quickly looking up key terms. The global shortcuts are:
SHORTCUT | ACTION |
|---|---|
Option+Shift+Command+? | Opens the help window |
Control+Shift+Command+? | |
Shift+Command+? | Activates the Help menu |
These three shortcuts are available almost universally in Xcode. The quick help window is described in the "Quick Help" section a little later in this chapter.
The next few sections describe other kinds of documentation shortcuts and how to access them.
You will most likely want to consult the documentation for a particular function or method while editing code. With a symbol name selected in the text editor pane, you have the following menu command and shortcuts available to you:
SHORTCUT | ACTION |
|---|---|
Option+Shift+double-click | Searches for symbol in documentation |
Option+double-click | Opens quick help window for symbol |
Control/Right-click | Searches for selected text in documentation |
Help | Same as Find Text in Documentation |
The two most useful shortcuts are the Option+Shift+double-click and Option+double-click gestures. These immediately select the word (symbol) underneath the cursor and search for its definition in either the help window or the quick help window (described in the next section).
The quick help window, shown in Figure 12-14, is a miniature help window that presents a succinct summary of a single API symbol. It operates in two modes: transient and persistent.
The quick help window has two action buttons, in addition to the standard title bar, resize, and close controls. The button with the little book jumps to the full API documentation for that symbol in the standard help window — equivalent to any of the other symbol search shortcuts mentioned in this section.
Note
If you have upgraded from an earlier version of Xcode, quick help replaces the Research Assistant. The "Persistent Quick Help" section described how to keep the quick help window open, where it acts very much like the Research Assistant did.
The optional header button jumps to the definition of the symbol in the framework's header (.h) file. This is equivalent to the Edit
Quick help is intended to be just that: quick. When summoned from the editor using the Option+double-click shortcut, it appears immediately adjacent to the symbol in question. Pressing the Esc key, or clicking anywhere in the editor pane, dismisses the quick help window and returns you to your coding.
If you summon the quick help window and then move or resize it, or open it using the Help
If you find yourself referring to the quick help window a lot, consider letting it be persistent. If you have limited screen real estate or, like me, only like to see it open when you need it, use the Option+double-click shortcut to open it on demand and press Esc to close it again.
The help document browser responds to the following standard shortcuts, although — oddly — most are not associated with any of Xcode's menus:
UNIX man pages are another source of documentation that is loosely integrated with Xcode. The C functions (section 3) of the man pages are included in the API search index. Looking up or searching for a POSIX C function displays the man page for that function, but the man pages for shell commands (section 1), file formats (section 5), system utilities (section 8), along with third-party man pages are not indexed and cannot be found through the help window.
To review any man page installed in your system, choose the Help
The man page name option invokes the man command with your search term and presents the resulting man page in the help window.
The search string option invokes the apropos (man -k) command. This searches all of the short descriptions in the man page database for the given keywords and presents the results in the help window. Each result is linked to its man page, so review the search results and click the entries that interest you.
The Documentation pane of the Xcode preferences, shown in Figure 12-16, allow you to customize three things: what documentation sets you subscribe to, what information is presented in the quick help window, and how small the documentation text fonts are allowed to be.
Any or all of the documentation sets installed in /Developer/Documentation can be maintained through an RSS feed. Xcode can query these RSS feeds to determine if there are any updates to the documentation sets. If new documentation is available, Xcode will offer to (or will automatically) download the updated documentation and install it. Downloading documentation from Apple's servers requires that you provide your developer connection account ID and password, as shown in Figure 12-17. This information will be saved for future updates. Installing new files in your /Developer folder also requires an administrator's authorization.
The Check For And Install Updates Automatically option instructs Xcode to periodically check for, and install, new documentation updates. If left unchecked, you will want to manually check for updates occasionally using the Check and Install Now button, preferably when you have a high-speed Internet connection — documentation updates can be quite large. In Figure 12-16, you can see that the iPhone OS 3.0 and Snow Leopard Library documentation sets are in the process of being downloaded. Be patient; even with a fast network pipe, large documentation sets can take an hour or more to download and install. If you're wondering what the progress of the update is, check Xcode's Activity window, as shown in Figure 12-18.
A number of documentation sets have subscription feeds, but are disabled by default. In Figure 12-16, the original iPhone OS Library, Java Library, and some other sets are not installed. Click the Get button to download, install, and activate the RSS feed for that document set. If you're curious about where the files for a particular document set are installed, the address of its RSS feed, and other information, click the small i (Info) button next to the set name.
You cannot delete any of the preinstalled document sets from Apple, but you can install additional sets generated by you or a third party. The details of generating and installing your own Xcode-compatible documentation is amply described in the article "Using Doxygen to Create Xcode Documentation Sets," which is part of the Xcode documentation set.
This chapter has focused on the help and documentation resources accessible through the Xcode interface, but one of the most valuable resources for Xcode users is other Xcode users.
In addition to supplementary developer information at Apple's Developer Connection web site, you'll also find a variety of mailing list and discussion forums. You can see the complete list of the mailing lists at http://lists.apple.com/mailman/listinfo. Of particular interest is the Xcode-users mailing list. This list is populated by Xcode users from all over the world and is a phenomenal resource for solving problems with Xcode. I tapped the talented and helpful individuals of this list several times while writing this book. I would strongly urge you to join the Xcode-users list.
As with many Internet discussion groups, members contribute their time and knowledge as a courtesy to others and to support the community of Xcode users. Many are professional software engineers with busy schedules and none of them are obligated to help you. Be respectful of their time and efforts by adhering to these guidelines:
The list does not exist to solve your problems for you. Post questions only when you've read all the available documentation (which should include this book), searched the list archives for similar questions, and tried all of the solutions you can think of.
Be clear, concise, complete, and courteous.
Give something back. The list is a community of members helping members. If you know the answer to a question, or have a helpful suggestion, take the time to post it. You can't expect others to help you if you never help anyone else.
The list is not your personal soapbox. It's not a forum for rants and personal opinions. If you want to provide feedback to the Xcode developers, use one of the feedback links on Apple's website or file an enhancement request via the bug reporter (available to registered developers). In my experience, the Xcode development team is very open to suggestions that will improve Xcode.
The list is not Apple support. If you need technical, sales, or developer support from Apple, contact the appropriate party through ADC. Apple engineers have been known to monitor and answer questions on the list, but they cannot provide you with any kind of official support through the list.
Xcode includes a massive amount of documentation, and a variety of tools for working with it. You've seen how to search for keywords and symbols, and find API documentation from within the class browser and directly from within your source code. You can even add you own documentation, if you need to.
You may still not find what you are looking for in the local documentation. Remember to avail yourself of the Apple Developer Connection web site (http://developer.apple.com/). Apple's online resources contain many more articles, documents, and sample code than could ever be downloaded and stored locally, and these resources are updated constantly.