openFrameworks doxygen documentation style guidelines

Doxygen Style Guidelines

Do not fix bugs and document at the same time. Even if the bug is minor, please keep those changes separate. Code changes must be reviewed more carefully and slow down the document integration process. If you find a bug, file an issue here and fix it in a separate pull request.

• Attempt to keep documentation in the header files.
• Use complete sentences, simple words and clear grammar.
• Freely cross-reference other classes by simply writing their class::method() (e.g. including ofRectangle::setFromCenter() in your class description will link to that function).
• Documentation of base classes (super classes) will transfer to sub classes. Do not re-write documentation unless the overridden function's behavior has fundamentally changed.

Document the Class

/// \class ofClassName
/// \brief A one sentence summary of the class' function.
///
/// A set of paragraphs to summarize any important information about the class.
/// this section should have hard line breaks at 80 characters.  To ensure that
/// the documentation is readable in the source files themselves.
///
/// Brief code examples should be indented markdown style like this:
///
/// ~~~~~{.cpp}
/// ofColor myColor(127, 0, 0, 127);
///
/// float brightness = myColor.getBrightness(); // returns 127.
/// float scaleFactor = brightness / limit();   // returns 127 / 255.
///
/// ofColor myNormalizedColor = myColor / scaleFactor;
///                             // Divides the red, green and blue
///                             // components by the scale factor.
/// ~~~~~
///
/// By styling code in that way, it will be rendered with syntax highlighting
/// in the rendered doxygen document.
///
/// [Links][1] are also useful and should be used markdown reference
/// style to keep everything neat and orderly.
///
/// Tables are very useful and every attempt should be made to keep the tables
/// with in the 80 character width limit.
///
/// |   Typedef     |    PixelType     | Bit Depth | Min. Value | Max. Value  |
/// | ------------- | ---------------- | --------- | ---------- | ----------- |
/// | `ofColor`     | `unsigned char`  | 8         | 0          | 255         |
/// | `ofShortColor`| `unsigned short` | 16        | 0          | 65535       |
/// | `ofFloatColor`| `float`          | _varies_  | 0.0        | 1.0         |
///
/// [1]: http://en.wikipedia.org/wiki/Lerp_(computing) "Lerp"
///
class ofClassName{
public:  ...
};

Document the Methods

/// \brief A one sentence description of the function's purpose.
///
/// If needed, you can include markdown paragraphs with all of the features
/// (tables, links, etc) mentioned in the class documentation notes above.
/// Sometimes, it might be nice to include a simple one or two line code
/// snippet if the method is complex.
///
/// \param param0 A description of parameter 0.
/// \param param1 A description of parameter 1.
/// \param param2 A description of parameter 2.
/// \param param3 A description of parameter 3.
/// \returns The meaning of the value returned.
int myMethod(float param0,
             float param1,
             float param2,
             float param3 = 44);

Function documentation in one line.

/// \brief myMethod returns the sum of \p param0 and \param1.
int mySummingMethod(float param0, float param1);

Document the Member Variables

float myVariable;  ///< \brief The purpose / meaning of this variable.

float myVariable2;
    ///< \brief The purpose / meaning of this variable.  If you need to take  
    ///<        more room to talk about your variable, you can place it below  
    ///<        the variable.  Attempt to keep it to 80 characters width.

Document the Member Variables

float myVariable;  ///< \brief The purpose / meaning of this variable.

float myVariable2;
    ///< \brief The purpose / meaning of this variable.  If you need to take  
    ///<        more room to talk about your variable, you can place it below  
    ///<        the variable.  Attempt to keep it to 80 characters width.

Document Enumerations

    /// \brief A one line description of the enum.
    ///
    /// An extended descripotion of where and why the eunmeration is used.
    /// It can be multiple lines and may contain links to other classes using
    /// a "see also" tag.
    enum MyEnumeration
    {
        VALUE_0, ///< \brief A description of VALUE_0.
        VALUE_1  ///< \brief A description of VALUE_1.
    };

Named groups

Group functions that have something in common like this:

/// \name Group 1
/// \{

void function1();
void function2(); 

/// \}

/// \name Group 2
/// \{

void function3();
void function4();

/// \}

Other useful tags:

\sa is the "see also" tag. Useful for creating hyperlinks between documentation blocks. \warning For including "must not miss" warnings. For example, if the user is required to free memory, etc.

Examples

• ofColor.h and ofColor.cpp

Setting Up Doxygen for Local Testing

1. Download an executable doxygen binary for your platform. Downloads for OSX, Windows and Linux can be downloaded here.
2. After downloading the app, open the openFrameworks local development doxygen config file located at $OF_ROOT/libs/openFrameworksCompiled/project/doxygen/Doxyfile_dev.
3. Run the doxygen app to test your changes:

Submitting Documentation

1. Clone the openFrameworks repository (you may have done this already).
2. Check out the feature-documentation branch (git checkout feature-documentation).
3. Each file pair (e.g. ofColor.h and ofColor.cpp) should be documented in their own branch off of the feature-documentation branch to allow clean and concise pull requests back to the feature-documentation branch.
4. To create a branch to document ofColor.h and ofColor.cpp, make sure you followed step 2 and then create a new branch called documentation-ofColor (git checkout -b documentation-ofColor).
5. You are now working with the documentation-ofColor branch. Add your documentation and then push your changes to your online fork (e.g. git push origin documentation-ofColor).
6. Then go to <github.com> and issue a pull request against the https://github.com/openframeworks/openFrameworks/tree/feature-documentation branch.