Easy Code Documentation with Xcodeby Adam Behringer
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.
- 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
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.
Quit PathDemo and return to the project in Xcode.
Classesfolder 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
DemoViewas 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
Download the binary distribution for Mac OS X from the Doxygen web site.
Open the disk image and drag the Doxygen application to your
Launch the Doxygen application. The user interface provides a simple way to configure the documentation settings for your project. Let's do that now.
Click the Wizard button. A new window will be displayed. The Project tab should be displayed by default.
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:
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 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.
Click on the OK button to close the Wizard window and go back to the GUI front end.
Click on the Save button and specify a location in which to save the configuration settings you created. The location should be your
PathDemoproject folder. Use the default name
Specify the working directory as your
PathDemoproject folder too. Notice that we are using this folder for everything. That is perfectly normal.
Click on the Start button to generate the documentation.