Documenting your code in Xcode 4

Introduction

If you are like me – beginning with programming in Objective-C in Xcode and you were Java programmer previously, you will wonder how to write code comments in a similar way to JavaDoc.

Well, Apple obviously thinks that programmers do not need to write documentation. Otherwise they would implement a similar documentation tool such as Javadoc and do not force programmers to do nasty hacks to be able to do so.

However there is a way, even though it requires a few manual steps. This blog post is a step-by-step how-to guide to prepare your Mac OS X 10.7 and Xcode 4.3 to be able to generate documentation out of your code and let Xcode offer that documentation to you through its Organiser and also through Quick Help in Utilities area.

Xcode 4 Quick Help

Prepare the Appledoc application

We will need to build the Appledoc application as there is no official OS X package available. After having the binary builded we will need to distribute the binary and also a couple of templates required to build HTML documentation files into our system.

Check out the Appledoc web

Walk through Gentle Bytes website. We will use this free tool (BSD license) to generate documentation out of our source files.

Syntax of the code comments is described on Gentle Bytes comments page.

Clone github repository

We need to download the application in order to build it. Go into the directory where you hold Xcode projects and then type following command in Termial application:

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

This command will create appledoc directory and clone the project’s GIT repo there.

Build the application

Open the appledoc.xcodeproj file in Xcode.

Edit your Scheme by clicking Xcode menu > Product > Edit Scheme menu item (Cmd + <) and change the Build Configuration to Release.

Build Configuration

Build the project to get an executable binary.

Install the aplication

Let Xcode open the location of built appledoc executable.

Show appledoc in Finder

You can also find the location manually, just search in ~/Library/Developer/Xcode/DerivedData/ for appledoc directory with some randomly-generated suffix. Copy the appledoc executable into the /Applications directory. Having the executable in the /Applications directory will allow Xcode to run the tool as a build script.

appledoc binary location

Prepare documentation templates for use

Appledoc application requires a couple of templates to be able to generate Xcode documentation. Goto the appledoc directory (the one created by GIT in previous step) and copy the content of Templates sub-directory into ~/Library/Application Support/appledoc/. This is the default location the application searches for its templates in.

Appledoc templates

Configure your project

To ease our life we will configure our Xcode projects so that when we build our applications the documentation will be generated automatically as well as Xcode will be informed that the documentation was updated.

Create configuration file

Add this configuration file into your Xcode project directory and name it AppledocSettings.plist. Do not forget to change the red-marked options according to your needs. You can also play with the other options as well. More information can be found on the Gentle Bytes settings page.

<?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>com.yourcompanysite</string>

<key>--create-docset</key>

<true/>

<key>--ignore</key>

<array>

<string>ThirdParty</string>

<string>Libraries</string>

<string>Frameworks</string>

<string>Testing</string>

</array>

<key>--install-docset</key>

<true/>

<key>--docset-platform-family</key>

<string>macosx</string>

<key>--output</key>

<string>/tmp</string>

<key>--project-company</key>

<string>YourCompanyName</string>

<key>--project-name</key>

<string>YourProjectName</string>

<key>--project-version</key>

<string>YourDocumentationVersion</string>

<key>--keep-undocumented-objects</key>

<true/>

<key>--keep-undocumented-members</key>

<true/>

<key>--warn-undocumented-object</key>

<false/>

<key>--warn-undocumented-member</key>

<false/>

<key>--warn-empty-description</key>

<true/>

<key>--warn-missing-arg</key>

<true/>

<key>--warn-unknown-directive</key>

<true/>

<key>--logformat</key>

<string>xcode</string>

<key>--exit-threshold</key>

<integer>2</integer>

</dict>

</plist>

Create documentation target

Add a new target into your Xcode project (Mac OS X/Other/Aggregate target) and name it Documentation. The new target will allow us to get the documentation generated every time we build our projects.

Xcode 4 targets

Aggregate target

Add new Run Script

Add Run Script build phase into the Documentation target. The Run Script will give us a chance to enter shell script to run the Appledoc application and pass commands over to it.

Adding Run Script Build Phase

Configure Run Script

Add the shell script below into the Run Script shell command place.

# Build an Xcode documentation
/Applications/appledoc "$SOURCE_ROOT/$PROJECT_NAME"

Custom shell script

Set up the build scheme

Add Documentation target into the existing scheme so that the documentation is created every time you build your project. You can reach the screen below by clicking Xcode menu > Product > Edit Scheme menu item (Cmd + <).

Build Scheme

Enjoy 🙂

Every time you will build your project the documentation will be generated automatically and will be pushed to Xcode so you can start using your documentation immediately.

The only issue with Xcode 4 is it does not reload Quick Help cache upon documentation changes. The only way to get it reloaded is to restart Xcode. In Xcode 3, it was possible to reload the documentation by running an AppleScript command below. However, it does not work in Xcode 4 anymore.

tell application "Xcode"
  load documentation set with path
  "/Users/YourUserName/Library/Developer/Shared/Documentation/DocSets/
    com.yourcompanysite.YourProjectName.docset"
end tell

If you are interested to see the output documentation files the Appledoc tool creates, go to the directory below.

~/Library/Developer/Shared/Documentation/DocSets/