---

Finding Technical Information

Finding technical information about an unfamiliar technology or API symbol is an important and often time-consuming activity for software developers. Xcode includes an array of features to help you quickly find technical information as you work on your project.

The Xcode documentation window provides a consistent, intuitive user interface and a wide range of search options for viewing the HTML-based documentation in the ADC Reference Library. Xcode provides several ways for getting you to the information you seek: focused API search, title search, and text-based search.

• API Search is the fastest way to get to reference documentation from an editor window or in the Documentation window. “Searching For API Documentation” describes this method.

• Title Search finds documents with titles that start with or contain your search string.

• Full-Text Search provides a way to find conceptual and reference documentation on a particular subject. With this method you can look through the set of documents that deal with the area in which you’re interested. “Searching for Relevant Documentation” delves into this search method.

This chapter shows you how to use Xcode to find technical information. It also explains how to view the header files in Mac OS X frameworks and how to update the ADC Reference Library on your computer.

In this section:

Downloading Documentation
Searching For API Documentation
Searching for Relevant Documentation
Following Links
Finding Information in Headers
Summary

Downloading Documentation

Xcode hosts a library of documents, code examples, technical notes, and release notes about development for Mac OS X using Apple technologies. To view this documentation library, open the Xcode documentation window:

1. Launch the Xcode application.

2. Choose Help > Documentation.

The first time you open the Xcode documentation window, Xcode displays a Subscribe button for each documentation feed in the pane on the left, as shown in Figure 2-1.

To subscribe to the Mac OS X documentation feed:

1. Click the Subscribe button next to Apple Mac OS X 10.5.

2. In the authentication dialog, sign-in with your ADC member name and password.

3. After Xcode downloads the core documentation for Mac OS X, note that other Mac OS X documentation sets are listed along with Get buttons. If you want any of these additional documentation sets, click the corresponding Get Button.

The documentation library is updated more often than new versions of Xcode are released. To keep your local copy of the library up to date, Xcode periodically checks for updates to the library’s content. When an update is available, Xcode displays an update button in the documentation window, as shown in Figure 2-2. Before you click a documentation update button, make sure you’re able to authenticate as an administrator of your computer.

You can also check for updates at any time in the action menu at the bottom of the documentation window. In that menu, choose Documentation Set Updates > Check Now. See Xcode Workspace Guide for more information about downloading documentation.

Searching For API Documentation

Xcode makes it easy to find the API documentation for any Apple-defined symbol—including functions, classes, methods, data types, and constants.

Searching from the Documentation Window

The search field in the documentation window allows you to display a list of all known symbols that match a particular search string. As you type in the search string, Xcode dynamically builds and displays the list.

To find API documentation using a search string:

1. Launch Xcode and choose Help > Documentation.

2. In the DOC SETS list, select Core Library to define the scope of the search.

3. In the search bar, click the API and Starts With buttons.

4. Click in the search field and begin typing the name of the drawRect: method. Notice that each time you type a character, the list of matching symbols is reduced in size.

5. Stop typing when the list of matching symbols is reduced to just a few entries.

6. Select the entry for drawRect: in the NSView class. As shown in Figure 2-3, Xcode finds and displays the API documentation for this method in the content pane.

Searching from a Text Editor Window

As a convenience, Xcode can also locate the API documentation for a symbol directly from a text editor window.

1. Open the Hello project window.

2. Open the source file main.m in an Xcode editor window.

3. Scroll down and find the call to the NSApplicationMain function.

4. Option–double-click this function—that is, hold down the Option key and double-click the name of the function. Xcode opens the documentation window and displays reference information about this function.

The Research Assistant window (Help > Research Assistant) offers a concise view of essential reference documentation for a specific symbol. The information you can view in the Research Assistant includes a symbol’s declaration, description, and availability information.

1. Open the Research Assistant window by choosing Help > Research Assistant.

2. Open the source file HelloView.m in an Xcode editor window.

3. Scroll down and find the call to the initWithFrame: method inside the brackets.

4. Click anywhere inside initWithFrame: or double-click to select it.

Xcode displays reference information about this method in the Research Assistant window, as shown in Figure 2-4.

Searching for Relevant Documentation

The Full-Text Search mode in the documentation window lets you search the reference library for documents relevant to a particular search string.

To search all technical documentation:

1. Launch Xcode and choose Help > Documentation. Xcode opens the window and displays a documentation page.

   Note: After the first time you use the documentation window, Xcode remembers the last page you were viewing the next time you display the window.

2. Select the Core Library documentation set. This selection tells Xcode to search for Mac OS X documents.

3. In the search bar, click the Full-Text button and the Contains button.

4. Click in the search field, type the phrase Cocoa fundamentals, and press Return. Xcode finds documents that contain this phrase and lists them in order of relevance.

5. Select one of the items listed in the search results. If the item is located in your computer’s local storage, Xcode displays the relevant page of documentation in the viewing pane, as shown in Figure 2-5.

   Figure 2-5  Using the full-text search option in Xcode

   

   Note: Reference Library items whose location icon is a blue globe instead of a hard disk are not located in your computer. When you click them, Xcode sends the corresponding URL to your web browser, which displays the webpage containing the item.

Following Links

The document in Figure 2-5 contains a number of hypertext links to other pages in the library. By convention, links are displayed as blue text.

There are several ways to use these links:

1. Click any link in the viewing pane of the documentation window. Xcode displays the linked page in the same viewing pane. To return to the previous page, click the left arrow button above the viewing pane.

2. Command-click the same link. Now Xcode displays the linked page in a new Xcode window.

3. Option-click the link. This time, Xcode sends the page’s URL to your web browser.

Finding Information in Headers

As you work on an Xcode project, sometimes it’s useful to study the declarations and comments in a Mac OS X framework header. Typically, you already know the name of the header or the name of one of its symbols.

Finding Framework Headers

If you know the name of a header but not its location, you can use Xcode to locate the header in a framework included in your project.

For example, to locate a header in the AppKit framework:

1. In the project window, use the disclosure triangles to open the project group. The groups inside are called source groups. Source groups contain references to actual files somewhere on your hard disk.

2. Open up the source group named Frameworks, and select AppKit.framework. Xcode lists the header files contained in this framework in the detail view.

3. Click in the project window search field and slowly type a few letters—for example, “ap”. Notice how Xcode filters the list of header files dynamically as you type each letter, as shown in Figure 2-6.

   Figure 2-6  Searching for headers in a framework

   

Another way to find headers is to use Xcode’s Open Quickly command. When the insertion point is on the name of a header in a source editor, you can press Shift–Command-D to bring up a source editor window with the corresponding header file. Xcode looks for the header file in the standard header locations.

Figure 2-7 shows Open Quickly in action.

If you’re not editing a file or the insertion point is not over the name of a header, Xcode displays the Open Quickly dialog, as shown in Figure 2-8. You enter the name of header in the Path text field and click Open.

Finding Symbol Declarations

In “Searching from a Text Editor Window,” you learned how to find the API documentation for any Apple-defined symbol in your source code. Using a similar technique, you can also find the declaration for a symbol.

For example, to find the declaration for NSApplicationMain:

1. From the Hello project window, open the source file main.m.

2. Find the line where the function NSApplicationMain is called.

3. Command–double-click this function—that is, hold down the Command key and double-click the name of the function. Xcode opens the header file NSApplication.h and displays the declaration for NSApplicationMain, as shown in Figure 2-9.

   Figure 2-9  Header search results

   

Summary

This tutorial provided an overview of the Xcode features that allow you to download and search for technical information. First, this tutorial described the process of downloading and updating your local copy of developer documentation. It showed how to search for conceptual documentation as well as API documentation from the documentation window and from a source editor window. Finally, this tutorial showed how to locate the header files in a framework, and how to find the header that declares a symbol used in a source file.

---