Creating Documentation With Doxygen – Part 2

In the first part of this series, I showed how Doxygen can be set up to produce documentation based on comments in code for Objective-C. In this second part, I’ll show some examples of how individual methods and classes can be documented and how Doxygen can be integrated into an Xcode build to create a documentation set that can be viewed in the Xcode organizer.

Documenting the Code

Once you have your basic documentation build up and running, it’s time to start documenting your methods. (Actually, it was time to start documenting your methods when you first created the project, but better late than never!) There are various ways to indicate documentation comments but, with my Java background, my preference is to use the JavaDoc style:

/**
* Brief summary of what the method does
*
* Additional notes about how the method works, any special
* conditions, side-effects, references to algorithms, web resources, etc.
* @see http://mobileappdev.learningtree.com
*
* @param x description of x
* @param y description of y
* @return description of what the method returns
*/
- (BOOL)myMethodWithX:(int)x Y:(int)y
{
    // Code here ...
}

The documentation comment is distinguished from normal comments by the two asterisks at the start of the C block comment.

The Doxygen manual provides a complete list of the tags that can be used as additional markup but the example shown above covers the key elements.

Here is an example of the HTML output of a documented method:

dox

You will probably also want to add documentation comments as file headers to summarise the purpose of some classes. These will appear as descriptions at the top of each page that Doxygen creates for a each class.

Creating an Xcode Documentation Set

Referring to the documentation using a web browser is great for teams who have access to a shared server, but you can also create documentation sets for Xcode that are great if you are working offline somewhere.

Apple provide a convenient shell script that automates the process and this can be integrated into your build. The process is quite simple: First use the Doxygen GUI to save your Doxygen configuration as doxygen.config in the root directory of your project (the one that contains the .xcodeproj file). Then edit the build scheme for your project in Xcode and define a post-action for the Build phase, pasting the content of Apple’s script into the shell script window.

Now, when you build your project, a DoxygenDocs.docset file is created in your project directory and this appears in the documentation tab of your Xcode organizer. Full details, including the build script, are available from the Apple Developer Library.

Conclusion

Creating documentation with Doxygen is really simple to do and it can be integrated easily into the Xcode build process. You can send the HTML files to a web server to share between members of a team, create a documentation set that you can view in Xcode, or create a set of LaTeX sources that can be turned into a PDF or printed document.

If you are used to writing documentation comments in other languages, I think you’ll find Doxygen is a great solution to creating living documentation for your iPhone and iPad projects.

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.