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
Trang 1Help and Documentation
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 fi nding the correct method or constant can be your most diffi cult 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
➤
➤
➤
➤
➤
➤
➤
➤
➤
Trang 2208 ❘CHAPTER 12 HELP AND DOCUMENTATION
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 fi nd 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 fi nd 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 DOCUMENTATION WINDOW
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 ➪ Developer Documentation
(Command+Option+Shift+?) command Most of the other commands in the Help menu —
Help ➪ Xcode Help (Command+Shift+?), Help ➪ Xcode Quick Start, and Help ➪ Xcode
Release Notes — all open the help window to some predetermined content; these are essentially
built - in bookmarks
If you’ve used the help window in earlier versions of Xcode, you may fi nd the new one somewhat perplexing It’s actually a substantial improvement and has a pleasantly simplifi ed 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
➤
➤
➤
➤
➤
➤
Trang 3The 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 fi eld, 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
Browsing Documentation
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 ➪ Xcode Quick Start is a great place to start in general For questions about Xcode itself, the Help menu provides direct links to Xcode ’ s documentation (Help ➪ Xcode Help), and the latest release notes (Help ➪ Xcode Release Notes)
➤
➤
➤
FIGURE 12 - 1
Trang 4210 ❘CHAPTER 12 HELP AND DOCUMENTATION
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
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
Navigating Help Documents
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, fi lter, and sorting features,
like that shown in Figure 12 - 3
Trang 5The 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
FIGURE 12 - 3
FIGURE 12 - 4
The Documentation Window ❘ 211
Trang 6212 ❘ CHAPTER 12 HELP AND DOCUMENTATION
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
Bookmarks
Choose the Find ➪ Add to Bookmarks (Command+D) command, or choose the Add Bookmark For
‘ ’ command from the Bookmarks toolbar control to create a bookmark to the current document
Figure 12 - 5 shows adding a bookmark to the File Manager Reference page You can bookmark
a page, but you can ’ t bookmark a particular anchor within a page Bookmarks are added to the
Bookmarks toolbar control and are independent of the Bookmarks smart group in your project
FIGURE 12-5
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
➤
➤
➤
➤
Trang 7External Links
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 fi les, 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 fi le link may download the fi le 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
➤
➤
➤
➤
➤
➤
FIGURE 12-6
Trang 8214 ❘ CHAPTER 12 HELP AND DOCUMENTATION
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
SAMPLE PROJECTS
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
FIGURE 12-7