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