The help system for Xcode is called a 'documentation set' (or docset for short). Constructing a docset manually is a hell of a job. Nobody wants to construct XML files and references by hand. Fortunately there are quite a few (free!) tools that can extract comments from your code and translate them into neat docsets. There's appledoc, doxygen and headerdoc just to name a few. I decided to go for appledoc for its simplicity.
In this tutorial i will explain the steps necessary to get your code documentation up and running. This is part 1 about installing appledoc and configuration a build target. In part 2 i will explain more about the options and documentation syntax.
Integrating AppleDoc in your build
What we are doing in the next steps is:
- Add a build target
- Customize the build phase to call appledoc
- Add a readme file that is used as an introduction page
- Test the build and see if the documentation is generated correctly.
First, we need a new build target name Documentation. After firing up Xcode and loading your project to be documented, add a new build target. To do this, select your root project so that the project summary tab appears. On the bottom of the screen you will see an Add Target button. Click that.
On the build phases tab, click Add Build Phase.
The second red line is a folder structure that gets included in the final documentation. For my project, I used some images. Refer to the Syntax section later on how to include images in your docset.
And there you have it!! Your own integrated help. But don't think you are done, you have got a lot of typing to do. This is covered in the next part where I'll discuss the syntax to document your code.
Meanwhile, to get you started, you should decorate all your interfaces with at least a small description like so: