Home > 2011 Fall DPS913, iOS, iOS Cocoa Touch > How to use Apple developer documentation

How to use Apple developer documentation

September 5, 2011 Leave a comment Go to comments

This document will teach you how to use Apple developer documentation efficiently and effectively.

This document was most recently updated in September 2012.

.

You have learned that Objective-C and the Cocoa frameworks are designed (in part) to be largely self-documenting. However, as a beginner, and someone who is probably new to Objective-C, you’re not convinced yet. One of the information resources that will help convince you is the Apple developer documentation.

Should you buy a book that teaches you how to do iOS programming? Yes, probably. Which one? Well, it’s difficult to make recommendations that have relevance and accuracy over a period of time. Sorry. Visit a bookstore, and spend an hour or so browsing through the table of contents and foreword/introduction sections of a number of books. Pick one (or more) that you like.

Please note that even if you buy a book, you’ll still need to learn how to use the Apple developer documentation.

.

The goal of this document is to teach you how to use Apple developer documentation efficiently and effectively.

.

Where is the documentation?

Two places – online (Apple) and in Xcode. The online content is also available through Xcode, so let’s just look at Xcode.

So, in Xcode, how do I use the documentation? Essentially, there are two ways to begin using the documentation:

  1. On its own, as a “library”, which is displayed in its own window in Xcode
  2. When writing code, accessing code/context specific documentation

.

Documentation: On its own, as a “library”

In Xcode, on the Help menu, choose Documentation and API Reference.

Use left-side navigation and/or the jump bar to help you locate the documentation you want. Be on the lookout for special features, including the ability to obtain/download the documentation in PDF form.

For more information, see the section below, titled “Using full-fidelity help“.

.

Documentation: When writing code, accessing code/context specific documentation

As a beginner, let’s assume that there are three major code elements that you will typically want help with:

  1. Class – its purpose, usage, and members
  2. Method
  3. Property

.

In Xcode, position the cursor on top of a class name, or a property name, or one of the parts of a method name. Then, press and hold one of the following keyboard keys, and click with your mouse:

  • Command – to “Jump to Definition”
  • Option – to see a “Quick Help” popup

.

In our first lecture, we learned about the application delegate. It is a class named similar to <appname>AppDelegate. It includes a number of methods, and you learned that the methods are defined either in the superclass (i.e. the base or parent class), or in a “protocol”.

Let’s assume that you wanted to learn more about any of these methods – where they are defined, their purpose, etc. Open <appname>AppDelegate.m. Scroll down, until this line of code comes into view:

 

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {


.

Command+click – Jump to Definition

Position the cursor on top of one of the parts of the method name. For example, click somewhere on the “application:” part.

Then, press and hold the Command key, and click to “Jump to Definition”.

Xcode will “jump” to the source code module that holds the definition for the method. In this example, it shows you UIApplication.h, the header for the UIApplication class.

.

Notice the window title; it includes “…UIApplication.h”. Also, notice the method definition, with a light-blue background highlight.

Your initial conclusion is that the method is defined in the UIApplication class. That’s reasonable, but it isn’t correct in this situation. Often a “protocol” is defined in the same source code file as the class. Scroll up, and look for a protocol definition statement:

The lesson here is to look at the .h header file a bit more, to make sure you reach the right conclusion.

OK; great – we know where the method is defined – in the UIApplicationDelegate protocol. Tell me more…

.

Option+click – Quick Help

At this point in time, you can 1) “go back” by clicking the button on the jump bar, or 2) continue on from here. In both cases, we’re still going to focus on the “application:didFinishLaunchingWithOptions:” method.

Position the cursor on top of one of the parts of the method name. For example, click somewhere on the “application:” part.

Then, press and hold the Option key, and click to see “Quick Help”. You will see the following:

.

The small panel/window shows “Quick Help” info. If that amount of help isn’t enough, look for the icon that looks like a book; it is in the upper-right area of the small panel/window. Click it, and the full-fidelity reference documentation window will open:

.

Can I access full-fidelity documentation directly?

Well, it depends. Typically for class names and property names, the answer is “yes”.

However, if you try this for methods that are defined in the superclass or in a protocol, the small panel/window will tell you “Documentation not found”:

.

If it does this, then back up, and “Jump to Definition” before you try “Quick Help” or full-fidelity documentation.

.

Using full-fidelity help

The full-window, full-fidelity documentation will be helpful, but only if you know how to use it efficiently and effectively.

Let’s look a sequence of five screen shots, which enable us to start at the documentation’s “home” page,  search for a class reference document, and drill down to the detail we want.

Image 1 – the Apple Developer documentation “home” page

.

Image 2 – enter a search term

In the right-side search field (about half-way down the page), enter a search term. In this example, we are looking for UIView, so we entered “uiview”.

The window updated as we typed.

.

Image 3 – select what you want from the results list

Click “UIView Class Reference” from the results list.

.

Image 4 – learn how to use the jump bar to view the document contents

The jump bar, at the top of the content area, offers a convenient way to navigate.

Almost all reference documents have the same layout and navigation structure. On the jump bar, you will see (typically) these sections:

  • Overview
  • Tasks
  • Properties
  • Class Methods
  • Instance Methods
  • Constants
  • Revision History
  • Companion Guide(s) (if any)

.

.

On the left side of the jump bar, there is a “Related Files” icon. Sometimes the document that you are viewing is available in PDF format. Click to see if this is the situation.

.

Apple “Competencies” documentation

Apple has created a set of very readable documents to help you get started with Cocoa and iOS development. Highly recommended.

Cocoa Core Competencies

Cocoa Application Competencies for iOS

.


Advertisements
  1. No comments yet.
  1. No trackbacks yet.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: