iOS 7 Programming Fundamentals: Objective-C, Xcode, and Cocoa Basics (2014)

Part II. IDE

Chapter 8. Documentation

Knowledge is of two kinds. We know a subject ourselves, or we know where we can find information upon it.

—Samuel Johnson, Boswell’s Life of Johnson

No aspect of iOS programming is more important than a fluid and nimble relationship with the documentation. There is a huge number of built-in classes, with many methods and properties and other details. Apple’s documentation, whatever its flaws, is the definitive official word on how you can expect Cocoa Touch to behave and on the contractual rules incumbent upon you in working with this massive framework whose inner workings you cannot see directly.

The Xcode documentation installed on your machine comes in large chunks called documentation sets (or doc sets, also called libraries). You do not merely install a documentation set; you subscribe to it, so that when Apple releases a documentation update, you can obtain the updated version.

When you first install Xcode, the bulk of the documentation is not installed on your machine; viewing the documentation in the documentation window (discussed in the next section) may require an Internet connection, so that you can see the online docs at Apple’s site. This situation is untenable; you’re going to want a copy of the documentation locally, on your own machine.

Therefore, you should start up Xcode immediately after installation to let it download and install your initial documentation sets. The process can be controlled and monitored, to some extent, in the Downloads pane of the Preferences window (under Documentation); you can also specify here whether you want updates installed automatically or whether you want to click Check and Install Now manually from time to time. This is also where you specify which doc sets you want; I believe that the iOS 7 doc set and the Xcode 5 doc set are all you need for iOS development, but I have also heard rumors that the documentation window (discussed in the next section) does not work properly unless you also install the OS X 10.8 or 10.9 doc set. You may have to provide your machine’s admin password when a doc set is first installed.

In Xcode 5, doc sets are installed in your home Library/Developer/Shared/Documentation/DocSets directory.

WARNING

Unlike earlier versions of Xcode, Xcode 5 doesn’t let you access older doc sets. A third-party application such as Dash can be helpful here (http://kapeli.com/dash).

The Documentation Window

Your primary access to the documentation is in Xcode, through the documentation window (Help → Documentation and API Reference, Command-Option-Shift-?). Within the documentation window, the primary way into the documentation is to do a search; for example, press Command-Option-Shift-? (or Command-L if you’re already in the documentation window), type NSString, and press Return to select the top hit, which is the NSString Class Reference. Click the magnifying glass icon to limit the results to the iOS-related doc sets if desired.

There are two ways to see the results of a search in the documentation window:

Pop-up results window

If you’re actively typing in the search field, a dozen or so primary results are listed in a pop-up window. Click with the mouse, or navigate with arrow keys and press Return, to specify which result you want to view. You can also summon and hide this pop-up window whenever the search field has focus, by pressing Esc.

Full results page

When the search field has focus and the pop-up results window is not showing, press Return to see a page listing all results of the search; these results are listed on four separate pages, by category: API Reference, SDK Guides, Tools Guides, and Sample Code.

You can also perform a documentation window search starting from within your code. You’ll very often want to do this: you’re looking right at a symbol actually being used in your code (a class name, a method name, a property name, and so on) and you want to know more about it. Hold Option and hover the mouse over a term in your code until a blue dotted underline appears; then (still holding Option) double-click the term. The documentation window opens, and you are taken directly to the explanation of that term within its class documentation page. (Similarly, during code completion — discussed in Chapter 9 — you can click the More link to make this same move, jumping directly to the documentation on the current symbol.)

Alternatively, you can select text in your code (or anywhere else) and choose Help → Search Documentation for Selected Text (Command-Option-Control-/). This is the equivalent of typing that text into the search field in the documentation window and asking to see the full results page.

The documentation window behaves basically as a glorified web browser, because the documentation consists essentially of web pages. Indeed, most of the same pages can be accessed at Apple’s developer site, http://developer.apple.com; and you can open in your web browser the page you’re currently viewing in the documentation window: choose Editor → Share → Open in Browser, or click the Share button in the window toolbar and choose Open in Safari. Multiple pages can appear simultaneously as tabs in the documentation window: hold Command as you navigate, to navigate to a new tab — for example, Command-click a link, or Command-click your choice in the pop-up results window — or choose Open Link in New Tab from the contextual menu. You can navigate between tabs (Window → Select Next Tab), and each tab remembers its navigation history (Navigate → Go Back, or use the Back button in the window toolbar, which is also a pop-up menu).

A documentation page may be accompanied by an additional table of contents or additional details, or both. These are displayed in the Info pane at the right of the documentation window; to see it if it isn’t showing, choose Editor → Show Info, or click the rightmost button in the toolbar. The Table of Contents and Details are separate subpanes within the Info pane; to switch between them, click one of the icons at the top of the Info pane. For example, the NSString Class Reference page has a table of contents subpane linking to all the topics within the page, and a Details subpane linking to NSString’s class inheritance, its adopted protocols, and so forth. I’ll talk more about a class’s details later in this chapter. Some documentation pages may use the table of contents subpane to show the page’s place within a larger group of pages; for example, the String Programming Guide consists of multiple pages, and when you’re viewing one, the Table of Contents subpane lists all the pages of the String Programming Guide along with each page’s main topics.

When you encounter a documentation page to which you’re likely to want to return, make it a bookmark: choose Editor → Share → Add Bookmark or click the Share button in the toolbar and choose Add Bookmark, or (easiest of all) click the bookmark icon in the left margin of the documentation page. Bookmarks are displayed in a pane at the left of the documentation window; to see it if it isn’t showing, choose Editor → Show Bookmarks, or click the second-from-the-right button in the toolbar. Documentation bookmark management is simple but effective: you can rearrange bookmarks or delete a bookmark, and that’s all.

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.

WARNING

Unlike earlier versions of Xcode, Xcode 5 provides no overall documentation table of contents, and it doesn’t let you access a doc set’s “home page” listing all of that doc set’s documents. That page is present, however, and you can view it in your browser. I recommend that you locate the iOS 7 doc set inside your home Library/Developer/Shared/Documentation/DocSets folder, open it in the Finder with the Show Package Contents contextual menu command, drill down to Contents/Resources/Documents/navigation/index.html, drag that file into your browser, and bookmark it.

Class Documentation Pages

In the vast majority of cases, your target documentation page will be the documentation for a class. It’s important to be comfortable and conversant with the typical features and information provided by a class documentation page, so let’s pause to notice them (Figure 8-1).

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

A class documentation page makes particularly good use of the Details subpane of the documentation window’s Info pane, and it’s important to keep an eye on the Details information when you’re studying the class (in the web browser presentation, this information appears at the top of the class documentation page itself):

Inherits From

Lists, and links to, the chain of superclasses. One of the biggest beginner mistakes is failing to consult the documentation up the superclass chain. A class inherits from its superclasses, so the functionality or information you’re looking for may be in a superclass. You won’t find out aboutaddTarget:action:forControlEvents: from the UIButton class page; that information is in the UIControl class page. 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.

Conforms To

Lists, and links to, the protocols adopted by this class. Protocols are discussed in Chapter 10.

Framework

Tells what framework this class is part of. Your code must link to this framework, and import this framework’s header, in order to use this class (see Chapter 6).

Availability

States the earliest version of the operating system where this class is implemented. For example, UIDynamicAnimator (along with UIKit dynamics in general) wasn’t invented until iOS 7. So if you want to use this feature in your app, you must make sure either that your app targets only iOS 7 or later, or that your code never uses this class when your app is running on an earlier system.

Declared In

The header(s) where this class is declared. Unfortunately this is not a link; I have not found any quick way to view a header starting from within the documentation. That’s a pity, as it can often be worth looking at the header file, which may contain helpful comments or other details. You can open the header file from your project window, as explained later in this chapter.

Sample Code

If a class documentation page links to sample code, you might want to examine that code. (But see my remarks on sample code in the next section of this chapter.)

Related

If a class documentation page lists a related guide, you might want to click that link and read that guide. For example, the UIView class documentation page lists (and links to) the View Programming Guide for iOS. Guides are broad surveys of a topic; they provide important information (including, often, useful code examples), and they can serve to orient your thinking and make you aware of your options.

The body of the class documentation page is divided into sections, which are listed in the Table of Contents subpane of the Info pane:

Overview

Some class pages provide extremely important introductory information in the Overview section, including links to related guides and further information. (See the UIView class documentation page for an example.)

Tasks

This section lists in categorical order, and links to, the properties and methods that appear later on the page. Often, just looking over this list can give you the hint you’re looking for.

Properties, Class Methods, Instance Methods

These sections provide the full documentation for this class’s properties and methods. (A property is a method — usually two methods, a getter accessor and a setter accessor — but the documentation lists the property rather than the accessors.)

Constants

Many classes define constants that accompany particular methods. For example, to create a UIButton instance in code, you can call the buttonWithType: class method; the argument value will be a constant, listed under UIButtonType in the Constants section. (To help you get there, there’s a link from the buttonWithType: method to the UIButtonType section in Constants.) There’s a formal definition of the constant; you won’t usually care about this (but do see Chapter 1 if you don’t know how to read it). Then each value is explained, and the value name is suitable for copying and pasting into your code.

Finally, let’s talk about how a class documentation page lists and explains individual properties and methods. In recent years, this part of the documentation has become quite splendid, with good hyperlinks. Note the following subsections, after the property or method name:

Description

A short summary of what the property or method does.

Formal declaration

Read this to learn things like the method’s parameters and return type. (Chapter 12 explains how to read a property declaration.)

Parameters and Return Value

Precise information on the meaning and purpose of these.

Discussion

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

Availability

An old class can acquire new methods as the operating system advances; if a newer method is crucial to your app, you might want to exclude your app from running on older operating systems that don’t implement the method.

See Also

Lists and links to related methods. Very helpful for giving you a larger perspective on how this method fits into the overall behavior of this class.

Related Sample Code

It can sometimes be worth consulting the sample code to see how this method is used in real life.

Declared In

The relevant header file.

WARNING

Methods injected into a class by a category (Chapter 10) are often not listed on that class’s documentation page and can be very difficult to discover. For example, awakeFromNib (discussed in Chapter 7) isn’t mentioned in the documentation for UIButton or for any of its superclasses or protocols. This is a major weakness in Apple’s organization and display of the documentation. A third-party documentation display application such as AppKiDo (http://appkido.com) can be helpful here.

Sample Code

Apple provides plenty of sample code projects. You can view the code directly in the documentation window; sometimes this will be sufficient, but you can see only one class implementation or header file at a time, so it’s difficult to get an overview. The alternative is to open the sample code project in Xcode; click the Open Project button at the top of a sample code page in the documentation window. If you’re looking at the sample code in your browser at http://developer.apple.com, there’s a Download Sample Code button. With the sample code project open as a project window, you can read the code, navigate it, edit it, and of course run the project.

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. (Users who have not grasped UITouch handling, for instance, often find that the lightbulb goes on when they discover the MoveMe example.) 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.

My own assessment is that Apple’s sample code is uneven. Some of it is a bit careless or even faulty, while some of it is astoundingly well-written. It is generally thoughtful and instructive, though, 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.

Other Resources

Here is a survey of other useful resources that supplement the documentation.

Quick Help

Quick Help is a condensed rendering of the documentation on some single topic, usually a symbol name (a class or method). It appears with regard to the current selection or insertion point automatically in the Quick Help inspector (Command-Option-2) if the inspector is showing. Thus, for example, if you’re editing code and the insertion point or selection is within the term CGPointMake, documentation for CGPointMake 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, for build settings while editing a project or target, and so forth.

Quick Help documentation can also be displayed as a popover window, without the Quick Help inspector. Select a term and choose Help → Quick Help for Selected Item (Command-Control-Shift-?). Alternatively, hold down Option and hover the mouse over a term until the cursor becomes a question mark (and the term turns blue with a dashed underline); then Option-click the term.

The Quick Help documentation contains links. For example, click the Reference link to open the full documentation in the documentation window; click the header link to open the appropriate header file.

New in Xcode 5, you can inject documentation for your own methods into Quick Help. To do so, you’ll need to write a comment in either doxygen format (see http://www.stack.nl/~dimitri/doxygen/) or HeaderDoc format (search on “HeaderDoc” at http://developer.apple.com). I recommend doxygen, as being a de facto standard. The comment will precede the declaration or definition of a method (or the declaration of a property). For example:

/*!

Many people would like to dog their cats. So it is \e perfectly

reasonable to supply a convenience method to do so.

\param cats A string containing cats

\return A string containing dogs

*/

- (NSString*) dogMyCats: (NSString*) cats {

return @"Dogs";

}

The exclamation mark in the opening comment delimiter denotes that this is a doxygen comment, and the comment’s location automatically associates it with the dogMyCats: method whose definition follows. The backslashed expressions \e, \param, and \return are doxygen commands. The outcome is that when dogMyCats: is selected anywhere in my code, its documentation is displayed in Quick Help (Figure 8-2). The doxygen method description (or a \brief description if you supply one) is also displayed as part of code completion (see Chapter 9).

Figure 8-2. Documentation for a custom method, injected into Quick Help

Symbols

A symbol is a nonlocally defined term, such as the name of a class, method, or instance variable. If you can see the name of a symbol in your code in an editor in Xcode, you can jump quickly to the definition of the symbol. Select text and choose Navigate → Jump to Definition (Command-Control-J). Alternatively, hold down Command and hover the mouse over a prospective term, until the cursor becomes a pointing finger (and the term becomes blue with a solid underline); Command-click the term to jump to the definition for that symbol.

If the symbol is defined in a Cocoa framework, you jump to the declaration in the header file. If the symbol is defined in your code, you jump to the class or method definition; this can be very helpful not only for understanding your code but also for navigating it.

The precise meaning of the notion “jump” depends upon the modifier keys you use in addition to the Command key, and on your settings in the Navigation pane of Xcode’s preferences. By default, Command-click jumps in the same editor, Command-Option-click jumps in an assistant pane, and Command-double-click jumps in a new window. Similarly, Command-Option-Control-J jumps in an assistant pane to the definition of the selected term.

Another way to see a list of your project’s symbols, and navigate to a symbol definition, is through the Symbol navigator (Chapter 6).

An important and often neglected way to jump to a symbol definition whose name you know, even if you can’t see the name in the code before you, is to choose File → Open Quickly (Command-Shift-O). In the search field, type key letters from the name, which will be interpreted intelligently; for example, to search for applicationDidFinishLaunching:, you might type “appdid”. Possible matches are shown in a scrolling list below the search field; you can navigate this list with the mouse or by keyboard alone. Definitions in your own code are listed before declarations from Cocoa headers, so this, too, can be a rapid way of navigating your code.

Header Files

Sometimes a header file can be a useful form of documentation. It compactly summarizes a class’s instance variables and methods and may contain comments with helpful information that might be provided nowhere else. A single header file can contain declarations for multiple class interfaces and protocols. So it can be an excellent quick reference.

There are various ways to see a header file from an Xcode editor:

§ If the class is your own and you’re in the implementation file, choose Navigate → Jump to Next Counterpart (Command-Control-Up).

§ Show the jump bar’s Related Files menu (Control-1). The menu lets you jump to any header files imported in the current file (as well as any files that import the current file) and to the header files of the current class file’s superclasses and subclasses and so forth. Hold Option to jump in an assistant pane.

§ Select text and choose File → Open Quickly (Command-Shift-O), as I explained in the previous section.

§ Command-click a symbol, choose Navigate → Jump to Definition, or pass through Quick Help, as described in the previous sections.

§ Use the Symbol navigator.

All of these approaches require that a project window be open; File → Open Quickly requires an active SDK for effective operation, and the others all operate on specific windows or words in an open project. An alternative that works under all circumstances, even when no project is open, is to switch to the Terminal and use the open -h command to open a header file in Xcode. The argument may represent part of a header file’s name. The command is interactive if there’s an ambiguity; for example, open -h NSString proposes to open NSString.h or NSStringDrawing.h (or both, or neither). I wish this command were built into Xcode itself.

Internet Resources

Programming has become a lot easier since the Internet came along and Google started indexing it. It’s amazing what you can find out 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 documentation resources are available at http://developer.apple.com. These resources are updated before the changes are rolled into your doc sets for download. There are also some materials here that aren’t part of the Xcode documentation on your computer. As a registered iOS developer, you have access to iTunes videos, including the videos for all WWDC 2013 sessions (as well as for some earlier years), and to Apple’s developer forums (https://devforums.apple.com). Also, much of Apple’s documentation comes in an alternative PDF format, convenient for storing and viewing on an iPad. Even better, Ole Zorn’s Docsets app will let you download and browse entire doc sets on an iPad or iPhone; it isn’t freeware, but it’s open source (https://github.com/omz/DocSets-for-iOS), so it’s free if you’re willing to build it yourself.

Apple maintains some public mailing lists (http://lists.apple.com/mailman/listinfo). I have long subscribed to the Xcode-users group (for questions about use of the Xcode tools) and the Cocoa-dev group (for questions about programming Cocoa). The lists are searchable, but Apple’s own search doesn’t work very well; you’re better off using Google with a site:lists.apple.com term, or http://www.cocoabuilder.com, which archives the lists. Apple has not added a mailing list devoted to iOS programming; that’s what the developer forums are supposed to be for, but the interface for these is extraordinarily clunky, and this — plus the lack of openness (to Google and to the world in general) — has limited their usefulness.

Other online resources, such as forums, have sprung up spontaneously as iOS programming has become more popular, and lots of iOS and Cocoa programmers blog about their experiences. I am particularly fond of Stack Overflow (http://www.stackoverflow.com); it isn’t devoted exclusively to iOS programming, of course, but lots of iOS programmers hang out there, questions are answered succinctly and correctly, and the interface lets you focus on the right answer quickly and easily.