As a courtesy, this is a full free rendering of my book, Programming iOS 6, by Matt Neuburg. Copyright 2013 Matt Neuburg. Please note that this edition is outdated; the current books are iOS 10 Programming Fundamentals with Swift and Programming iOS 10. If my work has been of help to you, please consider purchasing one or both of them. Thank you!
Knowledge is of two kinds. We know a subject ourselves, or we know where we can find information upon it.
You don't remember Cocoa; you look it up!
No aspect of Cocoa 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 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 (because a new version of iOS has been released, or because there has been an incremental revision of the documentation), 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) requires an Internet connection, so that you can see the online docs at Apple’s site. Therefore, you should start up Xcode immediately after installation to let it download and install your initial documentation sets. The process can be 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 6.1 Documentation Set and the Xcode 4.6 Developer Library are all you need for iOS development. You may have to provide your machine’s admin password when a doc set is first installed.
Your primary access to the documentation is in Xcode, through the Documentation tab of the Organizer window (Window → Organizer and then click Documentation, or Help → Documentation and API Reference). I’ll refer to this as the documentation window, even though it’s really an aspect of the Organizer window.
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 any page open in the documentation window can be opened instead in your web browser: Control-click for the contextual menu and choose Open Page in Browser. Notice too the contextual menu for links within a documentation window, such as Copy Link and Open Link in Browser. When you’re trying to figure something out, the ability to spawn off a page as a secondary window in a browser while you go on searching in the Xcode documentation window can be very useful.
Each doc set has a home page, which you access from the Browse navigator (Editor → Explore Documentation) or from the first component of the jump bar. A typical home page presents a full list of documents, which can be sorted by column and filtered by keyword. Some home pages, such as the iOS 6.1 Documentation Set home page, also have a broad categorical list down the left side, which can similarly be used to filter the document list. In practice I rarely use these home pages, though they can come in handy when you’re looking for broad topic introductions (click Guides on the left). The Browse navigator (and the jump bar) can also be used to explore a doc set by category.
When you encounter a documentation page to which you’re likely to want to return, make it a bookmark (Editor → Add Bookmark). Bookmarks are accessed through the Bookmarks navigator (Editor → Documentation Bookmarks). Documentation bookmark management is simple but effective: you can rearrange bookmarks or delete a bookmark, and that’s all.
My chief way into the documentation — and, I suspect, most users’ chief way — is by searching (Editor → Search Documentation). Type a term into the search field (Help → Documentation and API Reference, Shift-Option-Command-?). Click the magnifying glass to choose Show Find Options if they aren’t showing. It’s important to set these options correctly:
Enter a search term in the search field, and pause. Search results are displayed in categories, in relevance order, in the navigation pane; click a result to view that page. One would like to perform this move — from seeing a list of results in the navigation pane to viewing the page for one of those results — without using the mouse, but I haven’t discovered a reliable way to do that.
It’s important also to be able to switch nimbly from editing code to consulting the documentation on a term used in that code. Here are two ways:
Hold Option and hover the mouse over a likely term in code, until the cursor becomes a question mark (and the term turns blue with a dashed underline); then rapidly Option-double-click the term. This, in my opinion, is much the best way, because it bypasses the search field altogether and actually performs the search for the correct term in the correct class in the main documentation display.
You can perform the same move during code completion (Chapter 9): select one of the terms offered as a completion, and click the More link at the bottom of the pop-up menu.
Don’t confuse searching the documentation with finding within the current page. To find within the current documentation page, make sure the focus is within the page itself (probably by clicking in the page), and then use the Edit → Find menu commands. Command-F summons a find bar, as in Safari.
A major difference between the display of a documentation page in Xcode and the display of the same page as a web page at http://developer.apple.com is that the latter often shows a Table of Contents column at the left side. In Xcode, this Table of Contents column is suppressed, which saves space, but makes it harder to get a sense for where you are in a document or a set of related documents. The intention is presumably that you should use the jump bar both to get your bearings and to navigate, though personally I find this approach clumsy and frustrating.
In the vast majority of cases, your target documentation page will be the documentation for a class. I have frequently spoken already of the importance of class documentation pages. A common move on your part will be to search on a class name in the documentation window. If you search on, say, NSString, the search result whose title is NSString Class Reference is the class documentation for NSString.
Let’s pause to notice the key features of a class documentation page. I’ll use UIButton as an example (Figure 8.1):
addTarget: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
frameproperty from the UIButton class page; that information is in the UIView class page.
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 isn’t mentioned in the document 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 can be helpful here (http://appkido.com).
These sections provide the full documentation for this class’s methods. In recent years, this part of the documentation has become quite splendid, with good hyperlinks. Note the following subsections:
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.
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.
When you look at a sample code page from your browser, there’s a button that reads Download Sample Code. In fact, the sample code may already be on your computer. When you look at the same sample code page in the documentation window, the same button will read Open Project. The sample code on your hard disk is zipped, so even if the code is already on your computer, it is first unzipped (into your Downloads folder). This policy of keeping the sample code projects zipped on your hard disk is a good one, as it prevents you from accidentally altering the original, and you are free to experiment with the unzipped copy.
If a sample code project was linked against the frameworks of an older SDK that isn’t installed on your computer, the project will be described in the Project navigator with the words “missing base SDK.” In earlier versions of Xcode, this situation could prevent you from building and running the project, and features that depend on indexing might not work. In Xcode 4.2 and later, however, the project should build and run regardless. To remove the “missing base SDK” annotation, edit the target, switch to Build Settings, and change the outdated Base SDK setting to Latest iOS.
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 generally very thoughtful and instructive and definitely a major component of the documentation, and that 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.
Here is a survey of other useful resources that supplement the documentation.
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 (Option-Command-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 while editing a nib, for build settings while editing a project or target, and so forth.
A slightly reduced version of the same Quick Help documentation can be displayed as a small floating window, without the Quick Help inspector. Select a term and choose Help → Quick Help for Selected Item (Shift-Control-Command-?). 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.
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 (Control-Command-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 General pane of Xcode’s preferences. For example, if you haven’t changed these settings from the 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, Control-Option-Command-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 method or class definition whose name you know, even if you can’t see the name in the code before you, is to choose File → Open Quickly (Shift-Command-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”. Header file declarations are intermingled with your definitions; for example, for
applicationDidFinishLaunching: the first listing is this method’s declaration in the Cocoa header file UIApplication.h, while the second listing is your own AppDelegate class’s implementation of this method.
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 and other helpful information — information that might be documented nowhere else. A single header file can contain declarations for multiple class interfaces and protocols. So it can be an excellent quick reference.
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.
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 2012 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 docsets 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). Cocoa-dev does permit iOS questions, but it is not heavily used for these. 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.