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.
If you'd like to create API documentation for your code, you have several options:
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.
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.
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.
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
PathDemo.pbproj in Xcode.
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.
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 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
PathDemo project folder. Use the default name
Specify the working directory as your
PathDemo project folder too. Notice that we are using this folder for everything. That is perfectly normal.
Click on the Start button to generate the documentation.
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.
Right-click (or Ctrl-click) on the PathDemo group in the left pane of your Xcode project and choose Add -> New Group.
Rename your new group
Right-click (or Ctrl-click) on the Documentation group and select Add -> Existing Files.
PathDemo project folder, find the
html folder. In that folder, select the file
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.
Choose Preferences from the Xcode menu.
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.
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.
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.
Expand the Target group in the left pane of Xcode.
Right-click on the PathDemo target and choose Add -> New Build Phase -> New Shell Script Build Phase.
Type the following into the Script text field:
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.
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.
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.
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:
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
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.
Build your project (press Cmd-B), and view the class documentation for DemoView to see the changes.
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
num declaration, this comment will be attached to
num variable in the documentation.
setDemoNumber method declaration, add the following
/** 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
declaration, it will describe this function in the documentation. Also,
notice that we were also able to describe a parameter by using the
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.
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.
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.