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;
//
) format./**
*/
) format./*****...
”..
). Ending with a period is actually required for proper Doxygen functionality.@brief
should be avoided.JAVADOC_AUTOBRIEF
.enum
or struct
, a comment can immediately follow the item being documented if it has a less-than character at the begining (/**<
*/
).@struct
, @fn
, @var
, @property
, @typedef
, etc.)@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.@return
tags will be lost.@return true if the given object represents a String equivalent to this string, false otherwise.
”@retval
details might be considered.@ref
just add parenthesis to the end of the name, e.g. someFunction()
.::
@return ::CA_STATUS_OK if successful, ::CA_MEMORY_ALLOC_FAILED if memory allocation fails, otherwise some other error value.
”