How to use Apple developer documentation

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

.

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 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”
  2. When writing code, accessing code/context specific documentation

.

Documentation: On its own, as a “library”

In Xcode, on the Help menu, choose Developer Documentation.

Use navigation and/or the search field 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, right-click. The menu will offer you two documentation-specific choices:

  • Jump to Definition
  • Quick Help

.

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:

code

.

Jump to Definition

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

Now, right-click, and choose Jump to Definition.

.

Xcode will “jump” to the 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 displays “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…

.

Quick Help

Continuing from the previous section, right-click on a part of the method, and choose Quick Help. In the following image, “application:” was right-clicked:

.

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:

.

As an alternative to right-clicking the class, property, or method name, you can use these mouse-and-keyboard actions:

  • Jump to Definition – Option + double click
  • Quick Help – Command + double click

.

Can I access “Quick Help” directly?

Do we always have to do these two steps in sequence? Can we just get Quick Help (and then full-fidelity documentation) in one step?

Well, it depends. Typically for class names and property names, the answer is “yes”. Just right-click the name, and choose Quick Help (or Command+double click).

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”.

.

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 upper-right search field, enter a search term. In this example, we are looking for UIView, so we entered “uiview”.

The window updated as we typed. The left side shows a results list. The right side shows a reference document.

.

Image 3 – select what you want from the left-side results list

Click “UIView” from the left-side results list. Notice that it has a purple-colored square, with a letter C inside – this tells you that it is a “Class” reference document.

Notice that the right-side reference document updates to show us the UIView Class Reference.

.

Image 4 – close the results list

In the search field, in the upper-right of the window, clear the search term by clicking the “X” icon/circle.

The results list disappears, showing us the reference document.

.

Image 5 – learn how to use the document navigator, and the document contents

Almost all reference documents have the same layout and navigation structure. On the left-side document navigator, it shows a table of contents, with (typically) these sections:

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

.

Not all reference documents have all sections. You can use the triangle-shaped expand/collapse icons to show and hide the sub-sections. Then, click on any section name to re-position the content.

.

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

.


  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

Follow

Get every new post delivered to your Inbox.

Join 45 other followers

%d bloggers like this: