AddThis Social Bookmark Button

Listen Print Discuss
Mac OS X > Excerpts >

Easy Code Documentation with Xcode
Pages: 1, 2, 3

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.