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 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.
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"
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
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
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 + <).
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
If you are interested to see the output documentation files the Appledoc tool creates, go to the directory below.