Classes should be documented thoroughly in the .H file. A synopsis of the class (what is meant to be used for, how it is meant to be used) should appear above the class. Also appearing above the class is any long documentation on member functions. Very short comments on member functions can appear to the right of the function in the class declaration.
The syntax for the comments for a class is as follows:
/************************************** CLASS <class-name> <short-summary> KEYWORDS <any keywords for cross referencing> DESCRIPTION <complete description> PATTERNS <any design patterns used> WARNING <anything users should be aware of> ****************************************/
It appears that the main things are section headings (CLASS, DESCRIPTION, ...) are in all caps and not indented at all. CLASS is required, all others are optional. KEYWORDS has significance in that words here will be used for cross referencing off the main index.
Within the class declaration special comment strings are needed to notify Cocoon of the existence of functions. This comment string is //// and must appear on the line above each member function. It also should appear one line above any variable, typedefs, or enumerated types that might be in the .H file. A comment in the form // GROUP: <group name> can be used to group related functions together. Note that no documentation is produced for any private members or data. An example follows
class RiRay3 {
public:
// GROUP: constructors
//// Default constructor
RiRay3();
//// Constructor taking
// [in] o Ray origin
// [in] v Ray direction
// [in] i Valid interval with respect to the length of v
RiRay3(const RiVector3 &o, const RiVector3 &v, const RiInterval &i);
//// Copy constructor
RiRay3(const RiRay3& r);
// GROUP: access functions
//// [out] Origin of the ray.
// Note that if i.Min != 0.0 then the actual origin will be
// be different from what is returned.
const RiVector3 &GetOrigin() const;
//// [out] Direction (and distance scale) of the ray.
const RiVector3 &GetDirection() const;
//// [out] Interval describing the valid range of the ray
RiInterval &GetInterval();
//// [in] t Ray value
// [out] Point corresponding to t.
RiVector3 GetPoint( RiReal t ) const;