For all external API elements, comments on classes, structures, enumerations, member functions and member variable declarations must enumerate all behaviors of the element, including error and exceptional conditions. These comments shall conform to the standards of the current documentation tool, Doxygen.

/**
 * Assignment operator for ByteBuffer.
 *
 * If the passed in, buffer is owned by its ByteBuffer instance, a copy
 * will be made in this instance, otherwise just the pointer will be
 * copied. The current contents of this ByteBuffer will be freed if
 * this ByteBuffer owns its buffer.
 *
 * @param buffer The buffer to assign to this ByteBuffer.
 *
 * @return A reference to this ByteBuffer instance.
 */
ByteBuffer &      operator=(const ByteBuffer &buffer);

/**
 * Information about the network status.
 */
typedef enum
{
    CA_INTERFACE_DOWN,   /**< Connection is not available. */
    CA_INTERFACE_UP    /**< Connection is Available. */
} CANetworkStatus_t;

• Remember that less is more - “don't repeat unnecessary information”.
• Inline comments must be single-line (//) format.
• Multi-line comments should follow the JavaDoc (/** */) format.
• Copyright and other blocks must not accidentally start with a line of asterisks such as one beginning “/*****...”.
• Comments should start with a brief summary of a single sentence terminated with a period (.). Ending with a period is actually required for proper Doxygen functionality.
• Explicit use of @brief should be avoided.
  • Configuration 'Doxygen' files should enable JAVADOC_AUTOBRIEF.
• Place comments directly before the item being documented.
  • If a comment is placed elsewhere, it can easily end up being applied to the wrong object.
  • If a comment is not near the item being documented, a developer can easily miss getting it updated when they touch the code.
• For compact declarations such as members of an enum or struct, a comment can immediately follow the item being documented if it has a less-than character at the begining (/**< */).
• Avoid using the doxygen tags declaring what is being documented (@struct, @fn, @var, @property, @typedef, etc.)
  • Doxygen itself even warns “Do not use this command if it is not absolutely needed, since it will lead to duplication of information and thus to errors.”
• @return tags are not needed for void functions and should be omitted.
• @return comments should not start with the type being returned, as Doxygen will automatically add that.
• Manual formatting in @return tags will be lost.
  • Look to Javadoc for how to describe return values in single sentences.
    • e.g. “@return true if the given object represents a String equivalent to this string, false otherwise.”
  • If a set of discrete values can be returned, adding a set of @retval details might be considered.
• For functions mentioned in the text of a comment to be recognized, instead of @ref just add parenthesis to the end of the name, e.g. someFunction().
• For types, globals, defines, etc. mentioned in the text of comments to be recognized, they normally need to be prefixed with proper scope, most commonly ::
  • e.g. “@return ::CA_STATUS_OK if successful, ::CA_MEMORY_ALLOC_FAILED if memory allocation fails, otherwise some other error value.”

• see also IoTivity C Coding Standards - Comments