Creating Documentation With Doxygen – Part 1

A lot of the students that attend the Learning Tree iPhone and iPad development courses are from a Java and C# background. Both these languages have a rich, well-established set of frameworks and tools to support large-scale development. Tools such as continuous integration builders and testing frameworks. One specific question I had on a course recently was about creating documentation from comments in code — specifically what is the equivalent of JavaDoc for iOS projects?

Something I have used with good results is the free and open source documentation helper Doxygen. Doxygen is common on C++ projects but also works very well with Objective-C (and C for that matter).

Binary distributions of Doxygen for Mac OS, Linux and Windows are available from , along with a source code archive if you are so inclined. Installation on Mac OS is a simple matter of opening up the .dmg file and dragging the .app file to your Applications folder.

If you are running Mountain Lion, once the application is installed you will need to hold down the control key to run the first time to confirm bypassing of the restrictions on running downloaded software. Doxygen then presents a convenient user interface to build the configuration file that defines how you want to document your project.

doxygen1

A good starting point is to use the Wizard setup. On the Project page, enter your working directory as your Xcode project directory, set the project name and directory for source code. checking the “Scan Recursively” check box. You also need to define the destination directory for the generated documentation — I usually make a doc directory in the root of the Xcode project but you might want to choose a directory on a local web server to make the files available to your development team.

On the Mode page, choose to document all entities and select C++ as the language for which you want to optimize the output (there is no Objective-C option but the C++ option works well, creating useful inheritance diagrams for your classes).

On the output page, you will probably want to uncheck the LaTeX option unless you want to create printed documentation using LaTeX. I leave everything else as the default, apart from going to the Expert tab and checking the JAVADOC_AUTOBRIEF box, which allows me to create JavaDoc style comments.

Once you are set up, you can generate the documentation using the “Run Doxygen” button on the “Run” tab.

doxygen2

If you haven’t added any documentation comments, you will just get the basic structure of the documentation, but it does show inheritance hierarchies, lists of files in your project and allows you to browse the code.

doxygen3

Creating documentation is rarely a programmer’s favourite task, but automated documentation tools can ease the pain by creating the bulk of the documentation automatically and by using comments to add specific details. Documentation created in this way is much more likely to stay up to date because it “lives” with the code, especially if you can tie it into your natural build cycle. In part 2 of this series, I’ll explore the documentation comments themselves in more detail and show how to integrate Doxygen into your build process.

Richard Senior

Type to search blog.learningtree.com

Do you mean "" ?

Sorry, no results were found for your query.

Please check your spelling and try your search again.