RTOS/rtems
1
0
Fork 0
forked from Imagelibrary/rtems
Code Pull Requests Activity

doxygen: score: adjust doc in rbtree.h to doxygen guidelines

Browse Source 
Update #3706.
This commit is contained in:
Andreas Dachsberger
2019-04-11 09:58:04 +02:00
committed by Sebastian Huber
parent 1e6a7c7aa6
commit f61a3f8524
1 changed files with 90 additions and 64 deletions
Download Patch File Download Diff File Expand all files Collapse all files

154
cpukit/include/rtems/score/rbtree.h
View File

@@ -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 * @brief Constants and Structures Associated with the Red-Black Tree Handler
* 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 #endif
/** /**
* @defgroup RTEMSScoreRBTree Red-Black Tree Handler * @defgroup RTEMSScoreRBTree Red-Black Tree Handler
* *
* @ingroup RTEMSScore * @ingroup RTEMSScore
* *
* The Red-Black Tree Handler is used to manage sets of entities. This handler * @brief Red-Black Tree 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 * The Red-Black Tree Handler is used to manage sets of entities. This handler
* a RBTree. The second data structure is rbtree Control which is used * provides two data structures. The rbtree Node data structure is included
* to manage a set of rbtree Nodes. * 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; 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. * 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(). * @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 * @brief Checks if this red-black tree node is off-tree.
* otherwise.
* *
* @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 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(). * @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 * In debug configurations, the node is set off tree. In all other
* configurations, this function does nothing. * 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 ) 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. * @brief Adds a child node to a parent node.
* *
* @param[in] child The child node. * @param child The child node.
* @param[in] parent The parent node. * @param[out] parent The parent node.
* @param[in] link The child node link of the parent node. * @param[out] link The child node link of the parent node.
*/ */
RTEMS_INLINE_ROUTINE void _RBTree_Add_child( RTEMS_INLINE_ROUTINE void _RBTree_Add_child(
RBTree_Node *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 * @brief Inserts the node into the red-black tree using the specified parent
* node and link. * node and link.
* *
* @param[in] the_rbtree The red-black tree control. * @param[in, out] the_rbtree The red-black tree control.
* @param[in] the_node The node to insert. * @param[in, out] the_node The node to insert.
* @param[in] parent The parent node. * @param[out] parent The parent node.
* @param[in] link The child node link of the parent node. * @param[out] link The child node link of the parent node.
* *
* @code * @code
* #include <rtems/score/rbtree.h> * #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. * @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. * 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. * yields unpredictable results.
* *
* @param[in] the_rbtree The red-black tree control. * @param[in, out] the_rbtree The red-black tree control.
* @param[in] the_node The node to extract. * @param[out] the_node The node to extract.
*/ */
void _RBTree_Extract( void _RBTree_Extract(
RBTree_Control *the_rbtree, RBTree_Control *the_rbtree,
@@ -232,10 +236,10 @@ void _RBTree_Extract(
* *
* The root node may change after insert or extract operations. * 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 root The root node.
* @retval NULL The tree is empty.
* *
* @see _RBTree_Is_root(). * @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. * @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( RTEMS_INLINE_ROUTINE RBTree_Node **_RBTree_Root_reference(
RBTree_Control *the_rbtree 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. * @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( RTEMS_INLINE_ROUTINE RBTree_Node * const *_RBTree_Root_const_reference(
const RBTree_Control *the_rbtree 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 * 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(). * 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 parent The parent of this node.
* @retval undefined The node is the root node or not part of a tree. * @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. * 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. * @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 * @brief Returns a reference to the left child pointer of the red-black tree
* node. * 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( RTEMS_INLINE_ROUTINE RBTree_Node **_RBTree_Left_reference(
RBTree_Node *the_node 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. * 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. * @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 * @brief Returns a reference to the right child pointer of the red-black tree
* node. * 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( RTEMS_INLINE_ROUTINE RBTree_Node **_RBTree_Right_reference(
RBTree_Node *the_node 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 * This function returns true if there are no nodes on @a the_rbtree and
* false otherwise. * 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 true There are no nodes on @a the_rbtree.
* @retval false There are 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 * @brief Checks if this node is the root node of a red-black tree.
* false otherwise.
* *
* The root node may change after insert or extract operations. In case the * 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 * node is not a node of a tree, then this function yields unpredictable
* results. * 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 true @a the_node is the root node.
* @retval false Otherwise. * @retval false @a the_node is not the root node.
* *
* @see _RBTree_Root(). * @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. * 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( RTEMS_INLINE_ROUTINE void _RBTree_Initialize_empty(
RBTree_Control *the_rbtree 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 * @brief Initializes this red-black tree to contain exactly the specified
* node. * node.
* *
* @param[in] the_rbtree The red-black tree control. * @param[out] the_rbtree The red-black tree control.
* @param[in] the_node The one and only node. * @param[out] the_node The one and only node.
*/ */
RTEMS_INLINE_ROUTINE void _RBTree_Initialize_one( RTEMS_INLINE_ROUTINE void _RBTree_Initialize_one(
RBTree_Control *the_rbtree, 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. * @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 node The minimum node.
* @retval NULL The red-black tree is empty.
*/ */
RBTree_Node *_RBTree_Minimum( const RBTree_Control *the_rbtree ); RBTree_Node *_RBTree_Minimum( const RBTree_Control *the_rbtree );
/** /**
* @brief Returns the maximum node of the red-black tree. * @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 node The maximum node.
* @retval NULL The red-black tree is empty.
*/ */
RBTree_Node *_RBTree_Maximum( const RBTree_Control *the_rbtree ); RBTree_Node *_RBTree_Maximum( const RBTree_Control *the_rbtree );
/** /**
* @brief Returns the predecessor of a node. * @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 * @retval node The predecessor node.
* the predecessor node. * @retval NULL The predecessor does not exist.
*/ */
RBTree_Node *_RBTree_Predecessor( const RBTree_Node *node ); RBTree_Node *_RBTree_Predecessor( const RBTree_Node *node );
/** /**
* @brief Returns the successor of a 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 ); RBTree_Node *_RBTree_Successor( const RBTree_Node *node );
/** /**
* @brief Replaces a node in the red-black tree without a rebalance. * @brief Replaces a node in the red-black tree without a rebalance.
* *
* @param[in] the_rbtree The red-black tree control. * @param[in, out] the_rbtree The red-black tree control.
* @param[in] victim The victim node. * @param victim The victim node.
* @param[in] replacement The replacement node. * @param[out] replacement The replacement node.
*/ */
void _RBTree_Replace_node( void _RBTree_Replace_node(
RBTree_Control *the_rbtree, RBTree_Control *the_rbtree,
@@ -466,8 +491,8 @@ void _RBTree_Replace_node(
/** /**
* @brief Inserts the node into the red-black tree. * @brief Inserts the node into the red-black tree.
* *
* @param the_rbtree The red-black tree control. * @param[in, out] the_rbtree The red-black tree control.
* @param the_node The node to insert. * @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 * @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 * stored in the node to insert. The separate key parameter is provided for
* two reasons. Firstly, it allows to share the less operator with * 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 * @retval true The inserted node is the new minimum node according to the
* specified less order function. * 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( RTEMS_INLINE_ROUTINE bool _RBTree_Insert_inline(
RBTree_Control *the_rbtree, RBTree_Control *the_rbtree,
@@ -567,9 +593,9 @@ RTEMS_INLINE_ROUTINE void *_RBTree_Find_inline(
* @param the_rbtree The red-black tree control. * @param the_rbtree The red-black tree control.
* @param offset The offset to the red-black tree node in the container structure. * @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 * @retval container The container of the first node of the specified red-black
* tree in postorder. * tree in postorder.
* @retval NULL The red-black tree is empty.
* *
* @see _RBTree_Postorder_next(). * @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 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. * @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 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(). * @see _RBTree_Postorder_first().
*/ */
@@ -624,7 +650,7 @@ void *_RBTree_Postorder_next(
size_t offset size_t offset
); );
/**@}*/ /** @} */
#ifdef __cplusplus #ifdef __cplusplus
} }