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 documentation should be limited to a single \brief. Additional information (e.g. code examples, or in-depth discussion) should live in the corresponding markdown document.

/// \brief A one sentence summary of the class' function.
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. This description is particularly 
///               long so we do our best to align it and make it readable.
/// \returns The meaning of the value returned.
int myMethod(float param0,
             float param1,
             float param2,
             float param3 = 44);

Function documentation in one line.

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

Document the Member Variables

/// \brief The purpose / meaning of this variable in one line.
float myVariable;

/// \brief The purpose / meaning of this variable in one line.
///
/// If you need to take more room to talk about your variable, you can
/// talk about it in a paragraph like this. Attempt to keep it to 80 
/// characters width.
float myVariable2;

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
{
    /// \brief A description of VALUE_0.
    VALUE_0,
    /// \brief A description of VALUE_1.
    VALUE_1  
};

Sections

Sections help organize documentation. Section names should use "Title Case" (e.g. Testing 1 2 and Three).

Group functions or variables that have something in common like this:

/// \section Section 1
/// \brief Function1 one is part section 1
void function1();

/// \brief function2 is also part of section 1
void function2(); 

/// \section Section 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. \throws It is unusual for functions in openFrameworks to throw exceptions, but if you are documenting such a function, make a note of it with this tag.

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_local.
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.