Producing Documentation with appledoc

"appledoc is command line tool that helps Objective-C developers generate Apple-like source code documentation from specially formatted source code comments. It's designed to take as readable source code comments as possible for the input and use comments as well as surrounding source code to generate visually appealing documentation in the form of HTML as well as fully indexed and browsable Xcode documentation set." - gentlebytes

How to use it?

Classes

You can describe the overview/abstract of a class using the following commenting block:

/**
 A viewcontroller that represents the current race and its state in the UI. Currently supports 
 exactly 4 dog views (ADEDogView)
 
 Conforms to UIAlertViewDelegate and ADERaceDelegate
 */
@interface ADERaceViewController : UIViewController 

In the above code snippet, we link to our own class ADEDogView, which appledoc converts so that in the documentation, the word ADEDogView becomes a link through to the documentation describing the ADEDogView class. We also state that the class conforms to two protocols. At present (e08e80a439479fbec5c5a44eb4fbaf352cb39ef9) appledoc does not automatically link through to Apple-provided help docset documents, so UIAlertViewDelegate is not converted to a link (ADERaceDelegate does convert to a link).

The class does not have a discussion section, so everything in the commenting block is taken as part of the overview/abstract section.

Properties

/**
 The dogs current trackPosition
 */
@property(nonatomic, assign) NSUInteger trackPosition;

It's helpful to include properties in your commenting, as without the commenting block, the property won't be picked up as a class "Task" and won't be automatically referenced by appledoc.

Methods

If we take the following method signature:

- (id)initWithFirstname:(NSString *)firstname surname:(NSString *)surname age:(NSUInteger)age trackPosition:(NSUInteger)trackPosition

appledoc allows us to specify certain properties of this method in a level of detail that we feel comfortable with. If all that we wish to do is give an overview as to what the method does, we could:

/**
 Designated initializer
 */
- (id) initWithFirstname:(NSString *)firstname surname:(NSString *)surname age:(NSUInteger)age trackPosition:(NSUInteger)trackPosition;

The first line of the commenting block will be converted into the method's overview/abstract section; it will also be used in the method's discussion section unless you set the --repeat-first-par to disable this. Please note that taking a new line will end the overview/abstract section, and what follows will be regarded as the next section.

We can then expand on this commenting block to include more background information about the method:

/**
 Designated initializer
 Creates a dog object, populating the dog's variables with the parameter passed 
 */
- (id) initWithFirstname:(NSString *)firstname surname:(NSString *)surname age:(NSUInteger)age trackPosition:(NSUInteger)trackPosition;

The second line ("Creates a dog..") will appear in the method's discussion section. It's important to note here that the discussion section does not appear in the "Quick help" option in Xcode 4, but rather only in the docset, so it's important not to put anything critical into this section; instead, use it as an opportunity to expand on points already made.

We can again expand on this commenting block to include information about the parameters that this method accepts:

/**
 Designated initializer
 Creates a dog object, populating the dog's variables with the parameter passed
 @param firstname the firstname of the dog
 @param surname the surname of the dog
 @param age the age of the dog
 @param trackPosition start position of the dog, this is used when determining if the dog has won the race
 */
- (id) initWithFirstname:(NSString *)firstname surname:(NSString *)surname age:(NSUInteger)age trackPosition:(NSUInteger)trackPosition;

Notice the @param keyword, it informs appledoc that what follows will use the format: . It's important to watch out for the exact spelling of the parameter name here because if the parameter is misspelt or missing, you will receive a validation warning when you try to create your docset using appledoc (this will not prevent you from creating a docset, but may affect how the automatic referencing in appledoc works)

Finally, we have the method's return type:

/**
 Designated initializer
 Creates a dog object, populating the dog's variables with the parameter passed
 @param firstname the firstname of the dog
 @param surname the surname of the dog
 @param age the age of the dog
 @param trackPosition start position of the dog, this is used when determining if the dog has won the race
 @return ADEDog successfully created dog object 
 */
- (id) initWithFirstname:(NSString *)firstname surname:(NSString *)surname age:(NSUInteger)age trackPosition:(NSUInteger)trackPosition;

Notice the @return keyword, indicating that what follows will use the format: . Please note that you don't have to name your return object.

You can also include: @exception, but exceptions are generally not thrown in Objective-C, so I haven't detailed how to use them here (for details on this, please see the Developer Links at the bottom of this page).

The above method example is using an instance method; however, the same information applies equally to class methods.

Protocols

Protocols work in the same manner as classes with additional documentation added, whether a method is required or optional. As the developer, you do not need to add anything to accommodate this.

Building the docset

Once you have your comments in place, you need to convert them into a docset using appledoc. You have two methods:

1. Command line with arguments
2. Command line and plist containing arguments

Command line with arguments

The simplest command that you can use to create a docset is:

appledoc --project-name AppledocExample --project-company "WilliamBoles" --company-id me.williamboles --output ~/help .

In order to run this command, you first need to navigate to the folder where your project lives. So the above command can be broken down into:

1. "AppledocExample" - is the name that I'm assigning to the documentation. Please note that the --project-name is case sensitive, so "AppledocExample" and "appledocExample" will produce two sets of documentation.
2. "WilliamBoles" - is the company name.
3. "me.williamboles" - is the reverse domain (this will be expanded to: "me.williamboles.AppledocExample.docset").
4. "~/help" - is the folder that will be used to create the docset before being moved on to Xcode.
5. "." - don't forget the dot!

Command line with Plist

Plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>--company-id</key>
<string>me.williamboles</string>
<key>--project-company</key>
<string>WilliamBoles</string>
<key>--project-name</key>
<string>AppledocExample</string>
<key>--output</key>
<string>~/help</string>
</dict>
</plist>

The above command can be broken down into:

1. "AppledocExample" - is the name that I'm assigning to the documentation. Please note that the --project-name is case sensitive, so "AppledocExample" and "appledocExample" will produce two sets of documentation.
2. "WilliamBoles" - is the company name.
3. "me.williamboles" - is the reverse domain (this will be expanded to: "me.williamboles.AppledocExample.docset").
4. "~/help" - is the folder that will be used to create the docset before being moved on to Xcode.

Command Line:

You need to navigate the folder where the plist exists (or point to the folder) and run the following command:

appledoc .

Important to note the "." at the end of that command

All Done

You should now be the proud owner of some lovely documentation 📚.