Using AppleDoc to generate Xcode help (Part 2)

PLEASE NOTE: This article was written for XCode 4.6.3 and may be outdated on some parts. See the AppleDoc issue tracker on github for more info.
Welcome to part 2. In part 1 I talked about what AppleDoc is, what it does, and how to install it in your build setup. But to actually use it is a different subject. Not a lot of documentation on how to actually use appledoc is available.
The lack of documentation is partly there because new work on AppleDoc is going on behind the scenes, and the author decided to remove the little documentation to avoid mistakes and misinformation. I found out a lot of syntax stuff on my own (partly by browsing the apple doc source code). I’d like to share my findings here, and hope that someday the official documentation gets published again. I will be happy to help writing them when the time comes.
Let us skip the history lesson and rejoice that appledoc is free and open source. Then read on to find out how to document your classes, methods, categories and enums.

Adding comments

If we looks at the generated documentation from the tutorial in part 1, you will notice that all the classes and other objects are there. You can see them, but there is no text. To add text to these generated pages, you will need to add comments in the header files. Here is an example of a single line comment for a ViewController (ViewController.h):
 /** This view controller is the main controller of this application */
@interface ViewController : UIViewController

It is important that you add two asterisks (*) and not one. This is to distinguish normal comments from documentation comments. Now, when we build the documentation target, the following should be the result (build, show organizer,  open documentation tab, [your project]:

You can also use multiple lines. You do not have to start each line with a ‘*’, but when you do, you need to do them all (otherwise the parser thinks you want to do a bullet list).
  * Both these comment styles are equivalent

Both these comment styles 
are equivalent
The comments you write can contain easy layout commands using a syntax called markdown. It lets you type Strong, Italics, headers and even tables to document your code. Consider the following example:
 /** This is some sample documentation

Above was the abstract, the rest of the comment is used for the
discussion section of the documentation. Notice I did an
unintentional line wrap. Just like html, the document will
reflow to fit the width of the available page.

Let's do a simple bullet list:

* this is the first line
* this is the second line

#Section two# 
That was a H1 header we just generated.  Want a hyperlink? Just 
type and it'll  magically turn
into a link.

Finally, a small table

| header1 | header2 | header3 |
| normal  |  center |  right  |
| cell    | cell    | cell    |
@interface ViewController : UIViewController


I find that pretty awesome. If you want to know all you can do with markdown, check this markdown reference/tutorial on Appledoc will understand most of it.

Classes, properties, methods

Until now, we’ve only added basic header comments to a class header file. Let’s apply what we’ve learned to the properties and method signatures:
 /** Documenting the sample class */
@interface SampleClass : NSObject

/** Documenting a property */
@property (nonatomic, strong) NSString *name;

/** Documenting an instance method */
-(id)initializeWithName:(NSString *)name;

/** Documenting a class method */
Now, when you build the documentation, you will get a warning: we didn’t document the name argument for initializeWithName! That’ll be our next step.

To fix this error, we need to learn a new trick to tell appledoc the which argument to document.
 /** Documenting an instance method
 @param name The name of the class
 @return Returns a named instance of SampleClass 
-(id)initializeWithName:(NSString *)name;
The @param directive is followed by the name of the property to be documented. The rest that follows is the explanation. Also note the @return directive (which is optional by the way). It does the same for the return value. As you see @return does not need a name.

This are the common directives:

  • @param [param name]
  • @returns
  • @see [classname, category name, enum typedef and such]
  • @since [version number]
  • @exception [exception]
  • @warning
  • @bug
  • @deprecated

These directive should work for all top-level objects. There are some edge cases that a directive is not fully supported though, keep that in mind. Finally there are some directives that are not supported but still caught by appledoc to be compatible with headerDoc-commented sources. These include @abstract, @brief and @discussion or @details. Sections listed under these 4 directives are automatically added to the relevant parts.

I want to close with a little tip. Appledoc builds up the documentation by parsing the source files of your project. It doesn’t use reflection on the compiled binary like the .Net document generators do. So appledoc needs to parse your files. It doesn’t check your project file to check what classes to document. Appledoc just enumerates the files and directories in your project folder and scans them all for source code. Remember that when you are suddenly confronted with strange classes in your documentation that you removed from the project earlier.
This should get you going.  As always, if you have questions, comments or suggestions, comment below or use the contact page. Happy Documenting!Rob.

Categorised in:

Comments are closed here.