[PATCH 43/98] doxygen: score: adjust doc in rbtree.h to doxygen guidelines
Sebastian Huber
sebastian.huber at embedded-brains.de
Tue May 7 05:39:48 UTC 2019
From: Andreas Dachsberger <andreas.dachsberger at embedded-brains.de>
---
cpukit/include/rtems/score/rbtree.h | 154 +++++++++++++++++++++---------------
1 file changed, 90 insertions(+), 64 deletions(-)
diff --git a/cpukit/include/rtems/score/rbtree.h b/cpukit/include/rtems/score/rbtree.h
index b63c5cb4c2..1e18d08fd3 100644
--- a/cpukit/include/rtems/score/rbtree.h
+++ b/cpukit/include/rtems/score/rbtree.h
@@ -1,10 +1,12 @@
/**
- * @file
+ * @file
*
- * @brief Constants and Structures Associated with the Red-Black Tree Handler
+ * @ingroup RTEMSScoreRBTree
*
- * This include file contains all the constants and structures associated
- * with the Red-Black Tree Handler.
+ * @brief Constants and Structures Associated with the Red-Black Tree Handler
+ *
+ * This include file contains all the constants and structures associated
+ * with the Red-Black Tree Handler.
*/
/*
@@ -27,17 +29,20 @@ extern "C" {
#endif
/**
- * @defgroup RTEMSScoreRBTree Red-Black Tree Handler
+ * @defgroup RTEMSScoreRBTree Red-Black Tree Handler
+ *
+ * @ingroup RTEMSScore
+ *
+ * @brief Red-Black Tree Handler.
*
- * @ingroup RTEMSScore
+ * The Red-Black Tree Handler is used to manage sets of entities. This handler
+ * provides two data structures. The rbtree Node data structure is included
+ * as the first part of every data structure that will be placed on
+ * a RBTree. The second data structure is rbtree Control which is used
+ * to manage a set of rbtree Nodes.
*
- * The Red-Black Tree Handler is used to manage sets of entities. This handler
- * provides two data structures. The rbtree Node data structure is included
- * as the first part of every data structure that will be placed on
- * a RBTree. The second data structure is rbtree Control which is used
- * to manage a set of rbtree Nodes.
+ * @{
*/
-/**@{*/
struct RBTree_Control;
@@ -76,7 +81,7 @@ typedef RB_HEAD(RBTree_Control, RBTree_Node) RBTree_Control;
*
* Do not use this function on nodes which are a part of a tree.
*
- * @param[in] the_node The node to set off-tree.
+ * @param[out] the_node The node to set off-tree.
*
* @see _RBTree_Is_node_off_tree().
*/
@@ -86,13 +91,12 @@ RTEMS_INLINE_ROUTINE void _RBTree_Set_off_tree( RBTree_Node *the_node )
}
/**
- * @brief Returns true, if this red-black tree node is off-tree, and false
- * otherwise.
+ * @brief Checks if this red-black tree node is off-tree.
*
- * @param[in] the_node The node to test.
+ * @param the_node The node to test.
*
* @retval true The node is not a part of a tree (off-tree).
- * @retval false Otherwise.
+ * @retval false The node is part of a tree.
*
* @see _RBTree_Set_off_tree().
*/
@@ -120,7 +124,7 @@ void _RBTree_Insert_color(
* In debug configurations, the node is set off tree. In all other
* configurations, this function does nothing.
*
- * @param[in] the_node The red-black tree node to initialize.
+ * @param[out] the_node The red-black tree node to initialize.
*/
RTEMS_INLINE_ROUTINE void _RBTree_Initialize_node( RBTree_Node *the_node )
{
@@ -134,9 +138,9 @@ RTEMS_INLINE_ROUTINE void _RBTree_Initialize_node( RBTree_Node *the_node )
/**
* @brief Adds a child node to a parent node.
*
- * @param[in] child The child node.
- * @param[in] parent The parent node.
- * @param[in] link The child node link of the parent node.
+ * @param child The child node.
+ * @param[out] parent The parent node.
+ * @param[out] link The child node link of the parent node.
*/
RTEMS_INLINE_ROUTINE void _RBTree_Add_child(
RBTree_Node *child,
@@ -153,10 +157,10 @@ RTEMS_INLINE_ROUTINE void _RBTree_Add_child(
* @brief Inserts the node into the red-black tree using the specified parent
* node and link.
*
- * @param[in] the_rbtree The red-black tree control.
- * @param[in] the_node The node to insert.
- * @param[in] parent The parent node.
- * @param[in] link The child node link of the parent node.
+ * @param[in, out] the_rbtree The red-black tree control.
+ * @param[in, out] the_node The node to insert.
+ * @param[out] parent The parent node.
+ * @param[out] link The child node link of the parent node.
*
* @code
* #include <rtems/score/rbtree.h>
@@ -213,14 +217,14 @@ RTEMS_INLINE_ROUTINE void _RBTree_Insert_with_parent(
/**
* @brief Extracts (removes) the node from the red-black tree.
*
- * This function does not set the node off-tree. In case this is desired, then
+ * This function does not set the node off-tree. In the case this is desired, then
* call _RBTree_Set_off_tree() after the extraction.
*
- * In case the node to extract is not a node of the tree, then this function
+ * In the case the node to extract is not a node of the tree, then this function
* yields unpredictable results.
*
- * @param[in] the_rbtree The red-black tree control.
- * @param[in] the_node The node to extract.
+ * @param[in, out] the_rbtree The red-black tree control.
+ * @param[out] the_node The node to extract.
*/
void _RBTree_Extract(
RBTree_Control *the_rbtree,
@@ -232,10 +236,10 @@ void _RBTree_Extract(
*
* The root node may change after insert or extract operations.
*
- * @param[in] the_rbtree The red-black tree control.
+ * @param the_rbtree The red-black tree control.
*
- * @retval NULL The tree is empty.
* @retval root The root node.
+ * @retval NULL The tree is empty.
*
* @see _RBTree_Is_root().
*/
@@ -248,6 +252,11 @@ RTEMS_INLINE_ROUTINE RBTree_Node *_RBTree_Root(
/**
* @brief Returns a reference to the root pointer of the red-black tree.
+ *
+ * @param the_rbtree The red-black tree control.
+ *
+ * @retval pointer Pointer to the root node.
+ * @retval NULL The tree is empty.
*/
RTEMS_INLINE_ROUTINE RBTree_Node **_RBTree_Root_reference(
RBTree_Control *the_rbtree
@@ -258,6 +267,12 @@ RTEMS_INLINE_ROUTINE RBTree_Node **_RBTree_Root_reference(
/**
* @brief Returns a constant reference to the root pointer of the red-black tree.
+ *
+ * @param the_rbtree The red-black tree control.
+ *
+ * @retval pointer Pointer to the root node.
+ * @retval NULL The tree is empty.
+ */
*/
RTEMS_INLINE_ROUTINE RBTree_Node * const *_RBTree_Root_const_reference(
const RBTree_Control *the_rbtree
@@ -273,7 +288,7 @@ RTEMS_INLINE_ROUTINE RBTree_Node * const *_RBTree_Root_const_reference(
* root node or a node that is not part of a tree. To test for the root node
* compare with _RBTree_Root() or use _RBTree_Is_root().
*
- * @param[in] the_node The node of interest.
+ * @param the_node The node of interest.
*
* @retval parent The parent of this node.
* @retval undefined The node is the root node or not part of a tree.
@@ -286,11 +301,11 @@ RTEMS_INLINE_ROUTINE RBTree_Node *_RBTree_Parent(
}
/**
- * @brief Return pointer to the left of this node.
+ * @brief Returns pointer to the left of this node.
*
* This function returns a pointer to the left node of this node.
*
- * @param[in] the_node is the node to be operated upon.
+ * @param the_node is the node to be operated upon.
*
* @return This method returns the left node on the rbtree.
*/
@@ -304,6 +319,10 @@ RTEMS_INLINE_ROUTINE RBTree_Node *_RBTree_Left(
/**
* @brief Returns a reference to the left child pointer of the red-black tree
* node.
+ *
+ * @param the_node is the node to be operated upon.
+ *
+ * @return This method returns a reference to the left child pointer on the rbtree.
*/
RTEMS_INLINE_ROUTINE RBTree_Node **_RBTree_Left_reference(
RBTree_Node *the_node
@@ -313,11 +332,11 @@ RTEMS_INLINE_ROUTINE RBTree_Node **_RBTree_Left_reference(
}
/**
- * @brief Return pointer to the right of this node.
+ * @brief Returns pointer to the right of this node.
*
* This function returns a pointer to the right node of this node.
*
- * @param[in] the_node is the node to be operated upon.
+ * @param the_node is the node to be operated upon.
*
* @return This method returns the right node on the rbtree.
*/
@@ -331,6 +350,10 @@ RTEMS_INLINE_ROUTINE RBTree_Node *_RBTree_Right(
/**
* @brief Returns a reference to the right child pointer of the red-black tree
* node.
+ *
+ * @param the_node is the node to be operated upon.
+ *
+ * @return This method returns a reference to the right child pointer on the rbtree.
*/
RTEMS_INLINE_ROUTINE RBTree_Node **_RBTree_Right_reference(
RBTree_Node *the_node
@@ -340,12 +363,12 @@ RTEMS_INLINE_ROUTINE RBTree_Node **_RBTree_Right_reference(
}
/**
- * @brief Is the RBTree empty.
+ * @brief Checks if the RBTree is empty.
*
* This function returns true if there are no nodes on @a the_rbtree and
* false otherwise.
*
- * @param[in] the_rbtree is the rbtree to be operated upon.
+ * @param the_rbtree is the rbtree to be operated upon.
*
* @retval true There are no nodes on @a the_rbtree.
* @retval false There are nodes on @a the_rbtree.
@@ -358,17 +381,16 @@ RTEMS_INLINE_ROUTINE bool _RBTree_Is_empty(
}
/**
- * @brief Returns true if this node is the root node of a red-black tree, and
- * false otherwise.
+ * @brief Checks if this node is the root node of a red-black tree.
*
* The root node may change after insert or extract operations. In case the
* node is not a node of a tree, then this function yields unpredictable
* results.
*
- * @param[in] the_node The node of interest.
+ * @param the_node The node of interest.
*
- * @retval true The node is the root node.
- * @retval false Otherwise.
+ * @retval true @a the_node is the root node.
+ * @retval false @a the_node is not the root node.
*
* @see _RBTree_Root().
*/
@@ -380,9 +402,11 @@ RTEMS_INLINE_ROUTINE bool _RBTree_Is_root(
}
/**
- * @brief Initialize this RBTree as empty.
+ * @brief Initializes this RBTree as empty.
*
* This routine initializes @a the_rbtree to contain zero nodes.
+ *
+ * @param[out] the_rbtree The rbtree to initialize.
*/
RTEMS_INLINE_ROUTINE void _RBTree_Initialize_empty(
RBTree_Control *the_rbtree
@@ -395,8 +419,8 @@ RTEMS_INLINE_ROUTINE void _RBTree_Initialize_empty(
* @brief Initializes this red-black tree to contain exactly the specified
* node.
*
- * @param[in] the_rbtree The red-black tree control.
- * @param[in] the_node The one and only node.
+ * @param[out] the_rbtree The red-black tree control.
+ * @param[out] the_node The one and only node.
*/
RTEMS_INLINE_ROUTINE void _RBTree_Initialize_one(
RBTree_Control *the_rbtree,
@@ -414,48 +438,49 @@ RTEMS_INLINE_ROUTINE void _RBTree_Initialize_one(
/**
* @brief Returns the minimum node of the red-black tree.
*
- * @param[in] the_rbtree The red-black tree control.
+ * @param the_rbtree The red-black tree control.
*
- * @retval NULL The red-black tree is empty.
* @retval node The minimum node.
+ * @retval NULL The red-black tree is empty.
*/
RBTree_Node *_RBTree_Minimum( const RBTree_Control *the_rbtree );
/**
* @brief Returns the maximum node of the red-black tree.
*
- * @param[in] the_rbtree The red-black tree control.
+ * @param the_rbtree The red-black tree control.
*
- * @retval NULL The red-black tree is empty.
* @retval node The maximum node.
+ * @retval NULL The red-black tree is empty.
*/
RBTree_Node *_RBTree_Maximum( const RBTree_Control *the_rbtree );
/**
* @brief Returns the predecessor of a node.
*
- * @param[in] node is the node.
+ * @param node is the node.
*
- * @retval NULL The predecessor does not exist. Otherwise it returns
- * the predecessor node.
+ * @retval node The predecessor node.
+ * @retval NULL The predecessor does not exist.
*/
RBTree_Node *_RBTree_Predecessor( const RBTree_Node *node );
/**
* @brief Returns the successor of a node.
*
- * @param[in] node is the node.
+ * @param node is the node.
*
- * @retval NULL The successor does not exist. Otherwise the successor node.
+ * @retval node The successor node.
+ * @retval NULL The successor does not exist.
*/
RBTree_Node *_RBTree_Successor( const RBTree_Node *node );
/**
* @brief Replaces a node in the red-black tree without a rebalance.
*
- * @param[in] the_rbtree The red-black tree control.
- * @param[in] victim The victim node.
- * @param[in] replacement The replacement node.
+ * @param[in, out] the_rbtree The red-black tree control.
+ * @param victim The victim node.
+ * @param[out] replacement The replacement node.
*/
void _RBTree_Replace_node(
RBTree_Control *the_rbtree,
@@ -466,8 +491,8 @@ void _RBTree_Replace_node(
/**
* @brief Inserts the node into the red-black tree.
*
- * @param the_rbtree The red-black tree control.
- * @param the_node The node to insert.
+ * @param[in, out] the_rbtree The red-black tree control.
+ * @param[out] the_node The node to insert.
* @param key The key of the node to insert. This key must be equal to the key
* stored in the node to insert. The separate key parameter is provided for
* two reasons. Firstly, it allows to share the less operator with
@@ -478,7 +503,8 @@ void _RBTree_Replace_node(
*
* @retval true The inserted node is the new minimum node according to the
* specified less order function.
- * @retval false Otherwise.
+ * @retval false The inserted node is not the new minimum node according to the
+ * specified less order function.
*/
RTEMS_INLINE_ROUTINE bool _RBTree_Insert_inline(
RBTree_Control *the_rbtree,
@@ -567,9 +593,9 @@ RTEMS_INLINE_ROUTINE void *_RBTree_Find_inline(
* @param the_rbtree The red-black tree control.
* @param offset The offset to the red-black tree node in the container structure.
*
- * @retval NULL The red-black tree is empty.
* @retval container The container of the first node of the specified red-black
* tree in postorder.
+ * @retval NULL The red-black tree is empty.
*
* @see _RBTree_Postorder_next().
*
@@ -614,8 +640,8 @@ void *_RBTree_Postorder_first(
* @param the_node The red-black tree node. The node must not be NULL.
* @param offset The offset to the red-black tree node in the container structure.
*
- * @retval NULL The node is NULL or there is no next node in postorder.
* @retval container The container of the next node in postorder.
+ * @retval NULL The node is NULL or there is no next node in postorder.
*
* @see _RBTree_Postorder_first().
*/
@@ -624,7 +650,7 @@ void *_RBTree_Postorder_next(
size_t offset
);
-/**@}*/
+/** @} */
#ifdef __cplusplus
}
--
2.16.4
More information about the devel
mailing list