Basic Notes

  • Comment at least each class and each public and protected member of a class.
  • Comment also every argument in a function.
  • Overridden functions need not be documented again, but indicate where the orginial function comes from (e.g., public cppexpose::Object interface).
  • Use active form for descriptions, do not use third person (e.g., ‘Get list of functions’, not: ‘Returns list of functions’).
  • Always indicate whether pointers can be null or not.
  • Always indicate the value range and/or units of arguments, return values and variables (e.g., ‘Delay in seconds’, not just ‘Delay’).
  • Add explanations and word definitions whenever necessary to clarify the overall software architecture. For example, a comment like ‘Get glyph decorator’ does not help much if it is unclear what a glyph decorator does exactly. So, explain it in the description of the class!

Example/Template

#pragma once
[...]


namespace gloperate
{


/**
*  @brief
*    Representation of a surface into which can be rendered
*
*    A surface is attached to a window or offscreen context and handles the
*    actual rendering. It should be embedded by the windowing backend and
*    receives state changes from the outside (such as window size, mouse, or
*    keyboard events) and passes them on to the rendering components.
*/
class GLOPERATE_API Surface : public AbstractSurface
{
public:
    cppexpose::Signal<> redrawNeeded;   ///< Called when the surface needs to be redrawn


public:
    /**
    *  @brief
    *    Constructor
    *
    *  @param[in] viewerContext
    *    Viewer context to which the surface belongs (must NOT be null!)
    */
    Surface(ViewerContext * viewerContext);

    /**
    *  @brief
    *    Destructor
    */
    virtual ~Surface();

    /**
    *  @brief
    *    Get OpenGL context
    *
    *  @return
    *    OpenGL context used for rendering on the surface (can be null)
    *
    *  @remarks
    *    The returned context can be null if the surface has not been
    *    initialized yet, or the method is called between onContextDeinit()
    *    and onContextInit() when the context has been changed.
    *    Aside from that, there should always be a valid OpenGL context
    *    attached to the surface.
    */
    AbstractGLContext * openGLContext() const;

    [...]

    /**
    *  @brief
    *    De-Initialize in OpenGL context
    *
    *    This function is called when the OpenGL context is destroyed.
    *    The object must release its OpenGL objects at this point.
    *
    *  @see onContextInit()
    */
    virtual void onContextDeinit();

    /**
    *  @brief
    *    Background color changed
    *
    *    This function is called when the viewer has changed its background,
    *    e.g., because a new theme is being applied.
    *
    *  @param[in] red
    *    Red color component (0..1)
    *  @param[in] green
    *    Green color component (0..1)
    *  @param[in] blue
    *    Blue color component (0..1)
    */
    virtual void onBackgroundColor(float red, float green, float blue);

    /**
    *  @brief
    *    Mouse button pressed
    *
    *    This function is called when a mouse button has been pressed inside the viewer.
    *
    *  @param[in] button
    *    Mouse button (see gloperate::MouseButton)
    *  @param[in] pos
    *    Mouse position (real device coordinates)
    */
    virtual void onMousePress(int button, const glm::ivec2 & pos);


protected:
    // Virtual AbstractSurface interface
    virtual void onInit() override;


protected:
    ViewerContext     * m_viewerContext; ///< Viewer context to which the surface belongs
    AbstractGLContext * m_openGLContext; ///< OpenGL context used for rendering on the surface
};


} // namespace gloperate