openFrameworks doxygen documentation style guidelines

Doxygen Style Guidelines

Doxygen is a popular in-line API documentation standard used in many open source software projects. The comment-based markup can be automatically converted to HTML, PDF or Markdown and can be interpreted by many IDEs (e.g. Xcode) to provide inline API help.

Inline openFrameworks documentation in Xcode.

Important notes before you get started:

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.

Do not fix "style" issues outside of the documentation blocks while documenting. Even if all those mixed up tabs and spaces and indentations are driving you absolutely crazy (we understand!) please submit those changes in a separate pull request.

Other tips!

• For code examples and comments, follow the oF style guide.
• Attempt to keep documentation in the header files.
• Use complete sentences, simple words and clear grammar.
• Add hard breaks in documentation at the 80 character mark for readability.
• 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 from base classes will automatically transfer to sub classes. Do not re-write documentation unless the overridden function's behavior has fundamentally changed. In these cases it is recommended to use the \copydoc command to avoid repetition.
• Before submitting a pull request, use the doxygen application and check for errors or missing documentation, etc.
• If you don't understand something that you are documenting leave a \todo marker and ask someone for feedback.

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 Enumerations

    /// \brief A one line description of the enum.
    ///
    /// An extended description of where and why the enumeration 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. Fork and clone a local copy of the target openFrameworks repository. If you are participating in a documentation sprint, there may be a recommended repository other than the main openFrameworks repository.
2. Each file pair (e.g. ofColor.h and ofColor.cpp) should be documented in their own branch to keep things clean and discussions focussed. After making a local clone, create and check out a new documentation branch for the file pair. For example, to document ofColor.h and ofColor.cpp you can create a and checkout a branch with git checkout -b documentation-ofColor.
3. 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).
4. Then go to <github.com> and issue a pull request against the https://github.com/openframeworks/openFrameworks/ master (or the target repository in step 1).
5. To continue, check out the original master branch from step 1 and repeat steps 2-5.