Documentation

Documenting Cappuccino is very important. This document will explain how to build the documentation, the style it should conform to and how to submit your changes.

Installation

Before helping out with documenting Cappuccino you’ll need to be able to build the documentation. The following steps will guide you through the installation process. If you don’t have the Cappuccino source code already see Getting-and-Building-the-Source for more information.

If you run Homebrew : brew install doxygen.

Or build Doxygen from source:

1. Download doxygen (http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc)
2. Place the doxygen executable somewhere on your path
3. Run jake docs in your Cappuccino directory

Style guide

The following section explain the style guidelines used for documenting the Cappuccino source code.

General Points

• Remember that the target audience are those who are unfamiliar with what you’re documenting.
• Comment block should use the Qt style and there should be no intermediate asterisks.

/*!
    Documentation goes here
*/

• Doxygen Commands are preceded with an ‘@’ symbol.

/*!
    @class CPWindow
*/

• Documentation should be written in clear and coherent sentences.
• Avoid very wordy descriptions but also avoid excessive summarisation.
• Do not insert HTML tags. To add a URL in the documentation simply include the http://… text and doxygen will automatically add the necessary HTML tags.
• To ignore a class or method insert a comment block before the item and use the “@ignore” command. Also add a comment block after the item and add the “@endignore” command.

/*! @ignore */ 
@implementation _internalStuff
@end
/!* @endignore */

Note: @ignore and @endignore are aliases to doxygen @cond and @endcond commands.