Document Better - Part 1

19 January 2014

Documentation is one of those things that every developer knows they should do, but few of us actually find the time for. Beginning with XCode 5, however, documentation is now in the developer's own best interest. Since XCode 5 supports the display of third party documentation within XCode's Quick Help pane.

The next step is to actually generate rich documentation for third parties to use. While HeaderDoc and DOxygen have been around for a while, having grown up within the Apple ecosystem, the styling leads something to be desired. From a practical standpoint, having to learn new documentation schema can result in additional costs to learn and become proficient with.

appledoc

appledoc is a Markdown based documentation generation program designed to look like Apple's own documentation. Though very complete, it is still in active development. I've found the developer community to be very responsive, with many tips available through their github issues page.

At the conclusion of a successful appledoc run a docset is generated. Docsets are the standard format that existing Apple Documentation stored. Once a docset is generated, you may access your custom documentation through the docset viewer of your choice. XCode's documentation viewer is available, but recently I have also become a fan of Dash, available on the Mac App Store for free, but in app purchase is availabe for - something, I forget. But, it is worth it.

This use guide has been constructed based on comments in the issues page, use of appledoc in production, and an examination of the source code.

Installing

The full install instructions can be found on appledoc's github page. They're very simple and boil down to the following steps:

  1. Clone the repository - git clone git://github.com/tomaz/appledoc.git

  2. Navigate to the location of your cloned local repository.

  3. Run the installation script - sudo sh install-appledoc.sh

That's it, you're done.

Alternatively you can install via Homebrew - brew install appledoc

Comment Blocks

Comment blocks are the source of all comments and notations for appledoc. When a token is preceeded by a valid comment block that token is included in the resulting documentation with the provided comments.

appledoc supports three types of comment blocks:

I find /*! to be preferable as it is supported by other popular documentation system, including XCode 5's Quick Help documentation. Naturally, these comment block still end in */.

The line formatting within comment blocks supply context to the final documentation. The first line is accepted as the "abstract" for the documentation element. Supply a blank line and then further documentation that will become the "discussion" section of the documentation.

/*! There's one space and between the exclamation point and the start of this sentence.

There's one blank line between the first line and this line. All the text that appears from this point on will also appear in the discussion block. So long as you don't add a blank line, the text will be
interpreted as a single paragraph. Even if you have an exteremly long line
and a short
one.

Then add a blank line and you'll start producing a new paragraph.
*/

Tokens

Most common elements of a program are supported as tokens that can be documented in appledoc. In some cases these element will generate whole, individual documents. In others, the token will be documented within another document. Still other tokens determine their inclusion status based on settings provided to appldoc.

As of appledoc 2.2 the typedefing of blocks does not get documented automatically, but more on that later.

Keywords

Keywords are the formatters that are used within comment blocks to layout the documentation for the commented token. abstract and discussion support implicit formatting based on their location within the comment block. Other keywords must pre prefixed with an "@" to be used.

Your First Documentation

Before you actually run your first appledoc build I recommend updating your .gitignore file, if you are using git for SCM. You'll want to add AppleDoc to your list of ignored folders. The standard run of appledoc includes this path as a location for the output files of the appledoc run.

Sample Code

For your review I have posted a sample project using appledoc to github.

Next Steps

Check back in about two weeks for part two of the appledoc use guide when I'll cover method groups, advanced scripting flags, and programming guides.