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 are able to 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 the UIAlertViewDelegate and ADERaceDelegate
 */
@interface ADERaceViewController : UIViewController 

In the above, 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 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).

Its important to note that unlike a method's commenting block, 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;

Its useful 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 as 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 a 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 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 its important not to put anything critical into this section but rather use it as an opportunity to expand on points all ready 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: . Its important to watch out for exact spelling of the parameter name here because if the parameter is misspelt of missing you will receive a validation warning when you 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 exactly 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 accomandate 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" the company name.
3. "me.williamboles" the reverse domain (this will be expanded to: "me.williamboles.AppledocExample.docset").
4. "~/help" 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" the company name
3. "me.williamboles" the reverse domain (this will be expanded to: "me.williamboles.AppledocExample.docset")
4. "~/help" 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 the proud owner of some lovely documentation 📚.

What do you think? Let me know by getting in touch on Twitter - @wibosco