Documentation Style Guide

This document will give a short overview of the style used when writing
documentation in Cappuccino. This is for API documentation and is intended
for comments and information that will be placed inside the framework Docs when
doxygen is run.

Please skim through this guide to ensure common documentation is generated across Cappuccino.

General Points:

• Comment block open and close are in Qt style (start with /*! and end with */)
• Doxygen Commands are preceded with an ‘@’ symbol (e.g. @class ).

• At the very least, with a new class in the framework, one should provide a Class documentation block with the correct group to add the class to and a brief and detailed decription of the class (see Documenting a Class).
• Write in coherent and clear sentences and try to remember that the target audience will probably be unfamiliar with the class.
• 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.

About Groups

Formatting Commands:

• Lists (LINK TO DOXY DOCS)
• To ignore a class or method: insert a comment block before the item and use the command “@ignore” and one at the end of the item to be ignored insert “@endignore” e.g.
  

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

  
  @ignore and @endignore are aliases to @cond and @endcond

Styles:

Documenting a Class:

Documenting Methods:

Documenting Public Variables and Constants:

Documenting Global Variables and Functions:

• Global Functions
• Enums

Example of What Not To Do:

Example of Good documentation: