Infinite Loop

Providing Custom Documentation in Xcode

Whenever you are writing code that is intended for reuse it is important that the API is well documented. This will make it a lot easier for other developers to understand and integrate your code. On top of this it will also make it a lot easier to reuse that code when you need to use it yourself 6 or 12 months down the road.

In this tutorial I will use ILGeoNames as an example for how you can easily generate documentation for your own projects.

I will use the appledoc tool provided by Gentle Bytes. The appledoc tool provides a lot of nice features including the ability to generate Apple-like html documentation as well as the ability to generate and install fully indexed and browsable Xcode documentation sets.

[AdSense - blog banner]

Installing appledoc

First we’ll need to install the appledoc tool. The easiest way to do this is to clone the source code from GitHub using the following command in the Terminal:

$ git clone git://github.com/tomaz/appledoc.git

This will create a folder called appledoc on your local machine containing the latest version of the source code. Inside you will find the Xcode project. Just open it and compile the appledoc target.

In order to make the tool generally available from the command line it must be copied to a location that’s included in the default search path. Personally I prefer to use /usr/local/bin but feel free to place it anywhere you like.

You must also copy the contents of the Templates directory to one of the locations expected by the appledoc tool. This can be done from the command line using the following commands:

$ sudo cp MY_XCODE_BUILD_OUTPUT_DIR/appledoc /usr/local/bin
$ mkdir ~/Library/Application\ Support/appledoc
$ cp -R appledoc/Templates/ ~/Library/Application\ Support/appledoc

To verify that appledoc have been sucessfully installed you can issue the following command in the Terminal:

$ appledoc --help

If everything is installed correctly the help page for appledoc will be printed to the Terminal window.

Generating the Documentation

In order to generate the documentation we’ll first create a new Aggregate target for the project called “Documentation”. That way the normal build will not be slowed down by generation of the documentation. Additionally any warnings or errors in the documentation will not cause the main target build to fail. If you want your documentation to automatically be updated every time you build the main target just add the “Documentation” target to the dependencies of the main target.

Next we’ll create a new Script Build Phase and add it to the “Documentation” target. This script will execute the appledoc tool. build the documentation files and install the documentation set into Xcode in one step.

Build Documentation Script Phase

All the appledoc settings are briefly described in the command line help we printed above. A more thorough description of each setting and their implications are available in the online documentation.

The most important ones in terms of Xcode build integration are --logformat xcode and --exit-threshold 2. These will ensure that any warnings or errors are logged in a format compatible with Xcode’s build output. Additionally, the build will only be marked as failed if errors are encountered. Undocumented classes or methods will just be flagged with a warning.

The --keep-undocumented-objects and --keep-undocumented-members settings ensures that all classes, methods, properties, etc. will be included in the documentation even if they are not explicitly documented. This also have the useful side effect of flagging any missing documentation with a warning in the build output making it easier to spot anything that’s been left out.

Besides parsing the comments and generating documentation files, the appledoc tool will finally install the finished documentation set into Xcode thus making it available for searching and browsing.

Writing the Documentation

So far the generated documentation doesn’t contain more than just an empty framework so the next step is to write it.

The appledoc tool makes it fairly easy to write the documentation since its syntax is based on human readable source code comments. In general appledoc uses a slightly modified version of the standard multiple line and single line comment styles of Objective C with a few extra markups, for example:

/** Query the geonames.org service for the name of the place near the given position (WGS84) 
 
 @param latitude The latitude for the position.
 @param longitude The longitude for the position.
 */
- (void)findNearbyPlaceNameForLatitude:(double)latitude longitude:(double)longitude;

This will displayed in the contextual Xcode Quick Help area like this:

I will not go deeper into the specific syntax for specifying the contents but the full documentation is available on the appledoc page on GitHub.

Conclusion

All in all appledoc is a great tool for quickly providing documentation for your code. Not only for other developers that adopts your code but also for yourself.

The only thing I have found missing in the tool (version 2.04 as of the writing of this post) is the lack of support for enums and constants. There is however a lively discussion on github regarding this topic so I expect this feature to find its way into appledoc in a relatively near future.

The Xcode project used in this post can be downloaded from GitHub.

Comments (5) | Trackback

5 Responses to “Providing Custom Documentation in Xcode”

  1. Rob says:

    Thanks for the post – very helpful. When I just checked out the github version he had it defaulting to building the tests not the appledoc executable; just select the Scheme drop down and change from AppledocTests to appledoc build target. Pretty simple unless you’re returning to cocoa coding from an absence of a couple of years like me ;)

  2. Rob says:

    If you get the docs to build, easy to verify by hitting Control, Option, Command, ? which is a shortcut to open Quick Help in XCode 4. I got a crash the first time; not sure about why this happened but it worked thereafter.

    Another tidbit I found helpful was to use multiple –ignore switches like –ignore *Tests.h which seemed to help me only doc what I wanted.

    Wonder if I can control the warnings a bit more. Their helpful, but using the –keep-undocumented* switches seems to remind the hell out of me that I’ve not documented a property..kind of annoying but only if I can’t somehow opt out..will have to do more digging

  3. An insightful blog post there mate . Cheers for that !

  4. Devanshu says:

    I’m getting following sections in documentation:
    1)Class
    2)Categories
    2)Protocol

    I need to add fourth one named “Example” there.

    Please help me

  5. [...] La prima cosa da fare è installare appledoc. Il modo migliore è clonare i sorgenti del progetto pubblicati su GitHub in XCode e compilarli, così come riportato dalla sezione Quick Install del readme di progetto oppure dal paragrafo “Installing appledoc” dell’articolo Providing Custom Documentation in Xcode. [...]

Leave a Reply

*