6.3.4. Doxygen Guidelines

6.3.4.1. Group Names

Doxygen group names shall use CamelCase. In the RTEMS source code, CamelCase is rarely used, so this makes it easier to search and replace Doxygen groups. It avoids ambiguous references to functions, types, defines, macros, and groups. All groups shall have an RTEMS prefix. This makes it possible to include the RTEMS files with Doxygen comments in a larger project without name conflicts.

/**
 * @defgroup RTEMSScoreThread
 *
 * @ingrop RTEMSScore
 *
 * ...
 */

6.3.4.2. Use Groups

Every file, function declaration, type definition, typedef, define, macro and global variable declaration shall belong to at least one Doxygen group. Use @defgroup and @addtogroup with @{ and @} brackets to add members to a group. A group shall be defined at most once. Each group shall be documented with an @brief description and an optional detailed description. The @brief description shall use Title Case. Use grammatically correct sentences for the detailed descriptions.

/**
 * @defgroup RTEMSScoreThread
 *
 * @ingrop RTEMSScore
 *
 * @brief Thread Handler
 *
 * ...
 *
 * @{
 */

 ... declarations, defines ...

 /** @} */

/**
 * @addtogroup RTEMSScoreThread
 *
 * @{
 */

 ... declarations, defines ...

 /** @} */

6.3.4.3. Files

Each source or header file shall have an @file block at the top of the file. The @file block should precede the license header separated by one blank line. This placement reduces the chance of merge conflicts in imported third-party code. The @file block shall be put into a group with @ingroup GroupName. The @file block should have an @brief description and a detailed description if it is considered helpful. Use @brief @copybrief GroupName as a default to copy the @brief description from the corresponding group and omit the detailed description.

/**
 * @file
 *
 * @ingroup RTEMSScoreThread
 *
 * @brief @copybrief RTEMSScoreThread
 */

/**
 * @file
 *
 * @ingroup RTEMSScoreThread
 *
 * @brief Some helpful brief description.
 *
 * Some helpful detailed description.
 */

6.3.4.4. Type Definitions

Each type defined in a header file shall be documented with an @brief description and an optional detailed description. Each type member shall be documented with an @brief description and an optional detailed description. Use grammatically correct sentences for the detailed descriptions.

/**
 * @brief The information structure used to manage each API class of objects.
 *
 * If objects for the API class are configured, an instance of this structure
 * is statically allocated and pre-initialized by OBJECTS_INFORMATION_DEFINE()
 * through <rtems/confdefs.h>.  The RTEMS library contains a statically
 * allocated and pre-initialized instance for each API class providing zero
 * objects, see OBJECTS_INFORMATION_DEFINE_ZERO().
 */
typedef struct {
  /**
   * @brief This is the maximum valid ID of this object API class.
   *
   * This member is statically initialized and provides also the object API,
   * class and multiprocessing node information.
   *
   * It is used by _Objects_Get() to validate an object ID.
   */
  Objects_Id maximum_id;

  ... more members ...
} Objects_Information;

6.3.4.5. Function Declarations

Each function declaration or function-like macros in a header file shall be documented with an @brief description and an optional detailed description. Use grammatically correct sentences for the brief and detailed descriptions. Each parameter shall be documented with an @param entry. List the @param entries in the order of the function parameters. For non-const pointer parameters

  • use @param[out], if the referenced object is modified by the function, or

  • use @param[in, out], if the referenced object is read and modified by the function.

For other parameters (e.g. const pointer and scalar parameters) do not use the [in], [out] or [in, out] parameter specifiers. Each return value or return value range shall be documented with an @retval entry. Document the most common return value first. Use a placeholder name for value ranges, e.g. pointer in the _Workspace_Allocate() example below. In case the function returns only one value, then use @return, e.g. use @retval only if there are at least two return values or return value ranges. Use grammatically correct sentences for the parameter and return value descriptions.

/**
 * @brief Sends a message to the message queue.
 *
 * This directive sends the message buffer to the message queue indicated by
 * ID.  If one or more tasks is blocked waiting to receive a message from this
 * message queue, then one will receive the message.  The task selected to
 * receive the message is based on the task queue discipline algorithm in use
 * by this particular message queue.  If no tasks are waiting, then the message
 * buffer will be placed at the rear of the chain of pending messages for this
 * message queue.
 *
 * @param id The message queue ID.
 * @param buffer The message content buffer.
 * @param size The size of the message.
 *
 * @retval RTEMS_SUCCESSFUL Successful operation.
 * @retval RTEMS_INVALID_ID Invalid message queue ID.
 * @retval RTEMS_INVALID_ADDRESS The message buffer pointer is @c NULL.
 * @retval RTEMS_INVALID_SIZE The message size is larger than the maximum
 *   message size of the message queue.
 * @retval RTEMS_TOO_MANY The new message would exceed the message queue limit
 *   for pending messages.
 */
rtems_status_code rtems_message_queue_send(
  rtems_id    id,
  const void *buffer,
  size_t      size
);

/**
 * @brief Receives a message from the message queue
 *
 * This directive is invoked when the calling task wishes to receive a message
 * from the message queue indicated by ID. The received message is to be placed
 * in the buffer. If no messages are outstanding and the option set indicates
 * that the task is willing to block, then the task will be blocked until a
 * message arrives or until, optionally, timeout clock ticks have passed.
 *
 * @param id The message queue ID.
 * @param[out] buffer The buffer for the message content.  The buffer must be
 *   large enough to store maximum size messages of this message queue.
 * @param[out] size The size of the message.
 * @param option_set The option set, e.g. RTEMS_NO_WAIT or RTEMS_WAIT.
 * @param timeout The number of ticks to wait if the RTEMS_WAIT is set.  Use
 *   RTEMS_NO_TIMEOUT to wait indefinitely.
 *
 * @retval RTEMS_SUCCESSFUL Successful operation.
 * @retval RTEMS_INVALID_ID Invalid message queue ID.
 * @retval RTEMS_INVALID_ADDRESS The message buffer pointer or the message size
 *   pointer is @c NULL.
 * @retval RTEMS_TIMEOUT A timeout occurred and no message was received.
 */
rtems_status_code rtems_message_queue_receive(
  rtems_id        id,
  void           *buffer,
  size_t         *size,
  rtems_option    option_set,
  rtems_interval  timeout
);

/**
 * @brief Allocates a memory block of the specified size from the workspace.
 *
 * @param size The size of the memory block.
 *
 * @retval pointer The pointer to the memory block.  The pointer is at least
 *   aligned by CPU_HEAP_ALIGNMENT.
 * @retval NULL No memory block with the requested size is available in the
 *   workspace.
 */
void *_Workspace_Allocate( size_t size );

/**
 * @brief Rebalances the red-black tree after insertion of the node.
 *
 * @param[in, out] the_rbtree The red-black tree control.
 * @param[in, out] the_node The most recently inserted node.
 */
void _RBTree_Insert_color(
  RBTree_Control *the_rbtree,
  RBTree_Node    *the_node
);

/**
 * @brief Builds an object ID from its components.
 *
 * @param the_api The object API.
 * @param the_class The object API class.
 * @param node The object node.
 * @param index The object index.
 *
 * @return Returns the object ID constructed from the arguments.
 */
#define _Objects_Build_id( the_api, the_class, node, index )

6.3.4.6. Header File Examples

The <rtems/score/thread.h> and <rtems/score/threadimpl.h> header files are a good example of how header files should be documented.