seidbereit.de

As some of you might know, I have a strong Java background. Documenting my code just feels natural to me. That’s why I was wondering about how to document the code I write in XCode. I found a post on MacDevCenter which describes how to use Doxygen to generate Javadoc like documentations out of Objective-C code. Since this post is quite old (2004) and I want to draw some more attention on the possibilities of documentation in XCode, I’m going to refresh the steps necessary to setup Doxygen for XCode.

First of all you’ll need to get the OS X version of Doxygen from doxygen.org. Doxygen comes in a dmg image. Just copy the Doxygen application into your Application folder.

Further create a folder called Documentation inside your XCode project. All generated documentation will be created in this folder.

Now run Doxygen and set it up for your XCode project.

1. In Doxygen use the Wizard to set up your project:
2. In the first tab of the wizard, set up your projects name and version. Further set the source code destination directory as shown in the screenshot (remember to create the Documentation directory before). Enter the directories manually, since using the Select dialog will result in absolut paths. Relative paths allow us to move the project later without reference problems.:
3. The second tab (Mode) allows you to define wich output entities will appear. Select to also include undocumented entities. C++ is fine for language optimization :
4. The Output tab allows you to specify which output formats shall be generated. Make sure to check HTML with frames and navigation tree. Afterwards press OK to close the wizard. Configuring the Diagrams tab is optional:
5. As the second step in Doxygen save the configuration as file Doxyfile in your project folder and you’re done. Step 6 & 7 are optional and not required, as they will be performed automatically from within XCode. But you may perform them to test your configuration.
6. Set the location of you project directory in step 3.
7. Step 4: press “Start” and the generation shall begin. Afterwards check the Documentation directory in your project. A folder named html has been created inside it. Check the documentation by opening the index.html file. Congrats!

Now on to setting up XCode to automatically execute Doxygen on build.

1. Open your XCode project.
2. Add a new build phase (Script Build Phase) to your projects target:
3. Enter “/Applications/Doxygen.app/Contents/Resources/doxygen Doxyfile” as the Shell command:

On your next project build, the documentation shall be created. Try!
But wouldn’t it be nice to access that documentation from within XCode? So let’s set this up next.

1. Right click your project and add a new Group. Call this group “Documentation”
2. To that group add an “Existing File” and choose the index.html in your projects Documentation/html folder (Did you compile yet? You’ll need to, to have the folder and file created ). Don’t copy item to destination groups folder and set reference type relative to project.
3. Finally you’ll have to tell XCode that this is no regular html source file. Do this by setting its file type to “text.html.documentation”. Now the file should be opened in XCodes HTML viewer. If not, check your file type settings in XCodes preferences.

Now everything should be set up for you to create great source code documentation!! Now all you need to do is document your source code. I’ll post about this later, but to get you started check out http://www.stack.nl/~dimitri/doxygen/docblocks.html for a brief introduction. Everybody who ever used javadoc shall find himself comfortable instantly.