MacDevCenter    
 Published on MacDevCenter (http://www.macdevcenter.com/)
 See this if you're having trouble printing code examples


Programming With Cocoa

Easy Code Documentation with Xcode

by Adam Behringer
08/27/2004

Using Free Automated Tools to Keep Your Documentation up to Date

Modern computer languages have so many different methods, classes, and keywords, it's impossible to memorize them all. Furthermore, new classes and methods are added with each revision of the language, and old methods are depreciated. On top of this, millions of lines of custom code are constantly being written by software engineers all over the world.

The way that most programmers manage this sea of information is by increasing their knowledge of the foundational concepts of programming and using API documentation to efficiently look up the information they need to know.

For example, I often program in Java and Cocoa, so I find myself visiting the following documentation sites on a daily basis:

Web-based API documentation is great because it's usually the most up to date. (Books take time to publish.) Hyperlinks make it easy to drill down to the specific method or class variable that you have questions about. It's also simple to navigate from a class to a related class such as its superclass.

As a developer, you must not only use documentation but also provide it for your own code if you want to make it usable to others. Ask yourself whether your code will be useful to you years from now when the details are foggy, or whether it will be useful to the remainder of your team when you retire to an island with white sand beaches.

Providing up-to-date and easy-to-navigate API documentation is a big step in making your code accessible and useful. If you are a Macintosh developer, you can leverage the power of Xcode so that it requires minimal effort to create good documentation.

Options for Documentation

If you'd like to create API documentation for your code, you have several options:

Maintaining documentation and code separately

You could create HTML documentation by hand and try to keep it synchronized with your code. This would suck for you, of course, so let's move quickly on to the next option.

Language-specific code documentation

Many languages have a means to generate API code based on specially formatted comments in the code. A great example is the Javadoc tool for creating API documentation for Java. In fact, the official API specification for Java was itself generated with Javadoc. There are ways of creating documentation in other languages too. Perl has POD (Plain Old Documentation), which allows specially formatted comments to be extracted in a number of useful formats.

If you consistently program in one language, it's probably best to learn the documentation technology that's standard for that language. The language-specific tools are often familiar to other users of the those languages.

Related Reading

Cocoa in a Nutshell
A Desktop Quick Reference
By Michael Beam, James Duncan Davidson

Language-independent inline code documentation

If you prefer a Swiss Army knife approach to programming (as I do), you may work with many different languages depending on the specific task at hand. In that case, you will want to keep your tools as consistent as possible so that your total environment is not changing, and switches only from language to language. Xcode is great in this regard. I personally use it to code Java, C, Perl, Cocoa, WebObjects, and HTML. I am sure it works great for other languages too.

What about the API documentation technologies, though? Can we learn one set of conventions and apply it to all these languages? Apple has developed a technology called HeaderDoc, which provides multiple language support. There is also a cross-platform, multiple-language tool called Doxygen, which seems to be well supported in the developer community.

When deciding which documentation tools to use, be sure to consider the preferences of the community you work in, whether a company or an open source project. The idea here is teamwork. Most of the technologies I listed above are similar in their use and end result, so it is not worth getting in a holy war over your favorite documentation tool. For Bee Documents, a document management company that I founded, we experimented with all of those mentioned above and found that Doxygen worked best for our needs; therefore, that is what I will use for the examples below. However, the other tools can certainly work with Xcode too and will require only minor modifications to the steps we are about to walk through together.

Example with an Example

As an example, let's use one of the example projects that ships with Xcode. We'll use PathDemo since it's a fun program. If you installed the examples with Xcode, you can find the project in /Developer/Examples/Quartz/PathDemo/PathDemo.pbproj.

  1. Open PathDemo.pbproj in Xcode.

  2. Press Cmd-R to build and run the application. Play around with the application a little so that you can get an idea of what it does.

  3. Quit PathDemo and return to the project in Xcode.

  4. Expand the Classes folder in the left pane and take a look at the four files that you find there. There is a header and implementation file for a class called DemoView as well as a header and implementation file for PathDemoController. Each class has instance variables and methods. There are minimal comments, but there's no API documentation for someone wanting to use these classes. Instead, a developer intending to use one of these classes in their own code would have to read through the entire code in order to understand it.

Download and Run Doxygen

  1. Download the binary distribution for Mac OS X from the Doxygen web site.

  2. Open the disk image and drag the Doxygen application to your Application folder.

  3. Launch the Doxygen application. The user interface provides a simple way to configure the documentation settings for your project. Let's do that now.

    The user interface provides a simple way to configure the documentation settings for your project.
  4. Click the Wizard button. A new window will be displayed. The Project tab should be displayed by default.

  5. Fill in the text fields in the Project tab. The project name is PathDemo, the version is 1.0, both the source and destination directories are the path to the directory containing your source code files. See the following screenshot if you have questions:

  6. Switch over to the Mode tab. Set the desired extraction mode to "All entities" using the radio button. This will cause all variables and methods to be included in the documentation, regardless of whether we added specific descriptions.

    Switch over to the Mode tab.
  7. Switch to the Output tab. Check only the HTML check box, as this will be the only way in which we deliver our documentation for now. Once we go through the tutorial, I encourage you to come back and change these settings to see what types of output are possible.

    Switch to the Output tab.
  8. Click on the OK button to close the Wizard window and go back to the GUI front end.

  9. Click on the Save button and specify a location in which to save the configuration settings you created. The location should be your PathDemo project folder. Use the default name Doxyfile.

  10. Specify the working directory as your PathDemo project folder too. Notice that we are using this folder for everything. That is perfectly normal.

  11. Click on the Start button to generate the documentation.

Add Documentation to Xcode Project

Our last steps resulted in a set of HTML pages that provide some documentation of our project. The HTML was saved in a folder in our project directory. To make the documentation easy to access, let's add it to our Xcode project.

  1. Right-click (or Ctrl-click) on the PathDemo group in the left pane of your Xcode project and choose Add -> New Group.

    Right-click (or Ctrl-click) on the PathDemo group in the left pane of your Xcode project and choose Add -> New Group.
  2. Rename your new group Documentation.

  3. Right-click (or Ctrl-click) on the Documentation group and select Add -> Existing Files.

  4. In your PathDemo project folder, find the html folder. In that folder, select the file index.html.

  5. Now there is a convenient link to your documentation that you directly access from within your project. However, it might show the HTML code rather than the rendered web page when you click on the file. We can change this behavior in the Xcode preferences.

  6. Choose Preferences from the Xcode menu.

  7. Switch to the File Types tab, and find the text.html settings under the file/text group. Choose HTML File as the preferred editor and click on OK.

  8. You may need to close and reopen your project to get the documentation to render as HTML. When you do, spend some time exploring what is there.

What we have at this point is documentation that lists every method and variable from our classes. We have not created any special descriptions; so far everything has been automatic. We even added the documentation to your project so that you do not have to launch a web browser to read the documentation.

Making It Automatic

Right now it isn't too hard to update the documentation if our code changes. We can simply press Start in the Doxygen user interface. However, it would be nice if we could skip this step. We can do that by adding a step to our build process. That way, the documentation will be updated every time we build the project in Xcode. This is possible because Doxygen can run from the command line as well as from the GUI.

  1. Expand the Target group in the left pane of Xcode.

  2. Right-click on the PathDemo target and choose Add -> New Build Phase -> New Shell Script Build Phase.

    Right-click on the PathDemo target and choose Add -> New Build Phase -> New Shell Script Build Phase.
  3. Type the following into the Script text field: /Applications/Doxygen.app/Contents/Resources/doxygen Doxyfile

    This is a very simple script! All you are doing is calling the Doxygen program with the Doxyfile configuration as input. When you use the Doxygen user interface to change the configuration and save the changes to this file, the changes will be seen the next time you build the project.

    Close the Shell Script Info pane when you are done with it.

    Close the Shell Script Info pane when you are done with it.

Adding Descriptions to the Documentation

It's nice to have a list of all our methods, but to really help our team we will have to write some good descriptions that will let them figure out how to use the methods. There are many different ways to do this with Doxygen, and you can find them in the Doxygen manual. These steps will get you started.

  1. Let's start by editing DemoView.h. Open this file in the Xcode editor. It's often good to focus our documentation efforts on the header, as it describes the public interface to the class.

  2. Notice that DemoView.h has two block comments at the beginning of the file. Let's modify the comments so that they show up in the class documentation. Add an extra asterisk (*) to the opening of the comment. The first line will be:
    /**
    instead of:
    /*

  3. Now remove the comment closer (*/) from the first comment and the comment opener (/*) from the second comment so that all of the comment text at the beginning of the file is contained within one comment.

    Because our comment uses the double-asterisk opener and is at the top of the DemoView.h file, the contents of the comment will be used as the description for the DemoView class.

  4. Build your project (press Cmd-B), and view the class documentation for DemoView to see the changes.

  5. Let's add some more comments. Go back to the DemoView.h file and add the following line above the int num line:

    /** Stores the type of shape to draw. 0=rectangles,
    1=circles,2=bezierPaths, 3=circle clipping */

    Because the comment starts with the double asterisk and is directly before the num declaration, this comment will be attached to the num variable in the documentation.

  6. Before the setDemoNumber method declaration, add the following comment:

    /**
       Called by the interface to set the num variable
       @param newNum  an integer specifying the kind of shape to draw.
                      0=rectangles, 1=circles, 2=bezierPaths, 3=circle clipping
    */

    Because this comment is directly above the setDemoNumber function declaration, it will describe this function in the documentation. Also, notice that we were also able to describe a parameter by using the @param syntax.

  7. Build your project, and check out the documentation changes.

    Build your project, and check out the documentation changes.

Before we conclude, I want to show you one more way of adding comments to the code. It often creates cleaner-looking code when a comment is on the same line as a variable declaration. For example, open the PathDemoController.h file in Xcode and find the following lines:

    NSButton *button;
    NSPopUpButton *popup;
    NSWindow *window;
    DemoView *demoView;

Change those lines of code to the following:

    NSButton *button;	   /**< "Run Again" button in GUI	   */
    NSPopUpButton *popup;  /**< "Choose a path demo" popup in GUI  */
    NSWindow *window;	   /**< GUI window                         */
    DemoView *demoView;	   /**< Custom view for displaying shapes  */

By adding the > to the opening of the comment, we can use a comment that comes directly after the code that it refers to instead of placing the comment on the line above it. The documentation for Doxygen (or whatever document tool you choose to use) will have many little tricks like that, so be sure to check it out.

Final Thoughts

Automated API documentation for your code is easy to set up and even easier to maintain. Xcode can handle a lot of the repetitive work so that all you need to do is furnish some short descriptive comments as you maintain your code. Spend an hour or two evaluating the different documentation tools out there that work with your language of choice, and talk to your team about creating a policy for documenting code that way.

Something cool to consider is that because the documentation is integrated into the code, it works very well with a source control system such as CVS. If you check in your code for a daily build, that build could update the documentation on an intranet for all the developers. I'm interested (and I'm sure others are too) in learning how people are using automated code documentation in their real-world projects. I encourage you to leave a comment letting us know what your favorite documentation tools are and how you integrate them into your build system.

Happy documenting!

Resources

Adam Behringer works as the CEO of Bee Documents, which strives to help legal and medical firms efficiently manage their documents.


Return to MacDevCenter.com.

Copyright © 2009 O'Reilly Media, Inc.