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

Update #3706.

1 files changed, 289 insertions, 0 deletions

diff --git a/cpukit/include/rtems/score/priorityimpl.h b/cpukit/include/rtems/score/priorityimpl.h
index 3380983cb7..b33419acdb 100644
--- a/cpukit/include/rtems/score/priorityimpl.h
+++ b/cpukit/include/rtems/score/priorityimpl.h
@@ -1,3 +1,11 @@
+/**
+ * @file
+ *
+ * @ingroup RTEMSScorePriority
+ *
+ * @brief Priority Handler API Implementation.
+ */
+
 /*
  * Copyright (c) 2016 embedded brains GmbH.  All rights reserved.
  *
@@ -22,6 +30,17 @@
 extern "C" {
 #endif /* __cplusplus */
 
+/**
+ * @addtogroup RTEMSScorePriority
+ *
+ * @{
+ */
+
+/**
+ * @brief Initializes the priority actions empty.
+ *
+ * @param[out] actions The actions to be initialized empty.
+ */
 RTEMS_INLINE_ROUTINE void _Priority_Actions_initialize_empty(
   Priority_Actions *actions
 )
@@ -29,6 +48,14 @@ RTEMS_INLINE_ROUTINE void _Priority_Actions_initialize_empty(
   actions->actions = NULL;
 }
 
+/**
+ * @brief Initializes the priority actions with the given information.
+ *
+ * @param[out] actions The actions to be initialized.
+ * @param aggregation The aggregation for the @a actions to be initialized.
+ * @param node The action node for the @a actions to be initialized.
+ * @param type The action type for the @a actions to be initialized.
+ */
 RTEMS_INLINE_ROUTINE void _Priority_Actions_initialize_one(
   Priority_Actions     *actions,
   Priority_Aggregation *aggregation,
@@ -45,6 +72,14 @@ RTEMS_INLINE_ROUTINE void _Priority_Actions_initialize_one(
   actions->actions = aggregation;
 }
 
+/**
+ * @brief Checks if the priority actions is empty.
+ *
+ * @param actions The priority actions to check if it is empty.
+ *
+ * @retval true The priority actions @a actions is empty.
+ * @retval false The priority actions @a actions is empty.
+ */
 RTEMS_INLINE_ROUTINE bool _Priority_Actions_is_empty(
   const Priority_Actions *actions
 )
@@ -52,6 +87,14 @@ RTEMS_INLINE_ROUTINE bool _Priority_Actions_is_empty(
   return actions->actions == NULL;
 }
 
+/**
+ * @brief Checks if the priority actions is valid.
+ *
+ * @param aggregation The aggregation of the priority action.
+ *
+ * @retval true The @a aggregation is valid.
+ * @retval false The @a aggregation is not valid.
+ */
 RTEMS_INLINE_ROUTINE bool _Priority_Actions_is_valid(
   const Priority_Aggregation *aggregation
 )
@@ -64,6 +107,13 @@ RTEMS_INLINE_ROUTINE bool _Priority_Actions_is_valid(
 #endif
 }
 
+/**
+ * @brief Moves the priority actions' actions.
+ *
+ * @param[in, out] actions The priority actions to move the actions away from.
+ *
+ * @return The former actions of @a actions that were moved.
+ */
 RTEMS_INLINE_ROUTINE Priority_Aggregation *_Priority_Actions_move(
   Priority_Actions *actions
 )
@@ -76,6 +126,12 @@ RTEMS_INLINE_ROUTINE Priority_Aggregation *_Priority_Actions_move(
   return aggregation;
 }
 
+/**
+ * @brief Adds actions to the priority actions' actions.
+ *
+ * @param[in, out] actions The priority actions to add actions to.
+ * @param[out] aggregation The actions to add to @a actions.
+ */
 RTEMS_INLINE_ROUTINE void _Priority_Actions_add(
   Priority_Actions     *actions,
   Priority_Aggregation *aggregation
@@ -91,6 +147,12 @@ RTEMS_INLINE_ROUTINE void _Priority_Actions_add(
   actions->actions = aggregation;
 }
 
+/**
+ * @brief Initializes the priority node to the given priority.
+ *
+ * @param[out] node The priority node to be initialized.
+ * @param priority The priority to initialize @a node to.
+ */
 RTEMS_INLINE_ROUTINE void _Priority_Node_initialize(
   Priority_Node    *node,
   Priority_Control  priority
@@ -100,6 +162,12 @@ RTEMS_INLINE_ROUTINE void _Priority_Node_initialize(
   _RBTree_Initialize_node( &node->Node.RBTree );
 }
 
+/**
+ * @brief Sets the priority of the priority node to the given priority.
+ *
+ * @param[out] node The priority node to set the priority of.
+ * @param priority The new priority for @a node.
+ */
 RTEMS_INLINE_ROUTINE void _Priority_Node_set_priority(
   Priority_Node    *node,
   Priority_Control  priority
@@ -108,6 +176,11 @@ RTEMS_INLINE_ROUTINE void _Priority_Node_set_priority(
   node->priority = priority;
 }
 
+/**
+ * @brief Sets the priority node inactive.
+ *
+ * @param[in, out] node The priority node to set inactive.
+ */
 RTEMS_INLINE_ROUTINE void _Priority_Node_set_inactive(
   Priority_Node *node
 )
@@ -115,6 +188,14 @@ RTEMS_INLINE_ROUTINE void _Priority_Node_set_inactive(
   _RBTree_Set_off_tree( &node->Node.RBTree );
 }
 
+/**
+ * @brief Checks if the priority node is active.
+ *
+ * @param node The priority node that shall be verified if it is active.
+ *
+ * @retval true The priority node is active.
+ * @retval false The priority node is inactive.
+ */
 RTEMS_INLINE_ROUTINE bool _Priority_Node_is_active(
   const Priority_Node *node
 )
@@ -122,6 +203,11 @@ RTEMS_INLINE_ROUTINE bool _Priority_Node_is_active(
   return !_RBTree_Is_node_off_tree( &node->Node.RBTree );
 }
 
+/**
+ * @brief Initializes the priority aggregation empty.
+ *
+ * @param[out] aggregation The priority aggregaton to initialize empty.
+ */
 RTEMS_INLINE_ROUTINE void _Priority_Initialize_empty(
   Priority_Aggregation *aggregation
 )
@@ -137,6 +223,12 @@ RTEMS_INLINE_ROUTINE void _Priority_Initialize_empty(
   _RBTree_Initialize_empty( &aggregation->Contributors );
 }
 
+/**
+ * @brief Initializes the priority aggregation with the given information.
+ *
+ * @param[out] aggregation The priority aggregaton to initialize.
+ * @param node The priority node to initialize @a aggregation with.
+ */
 RTEMS_INLINE_ROUTINE void _Priority_Initialize_one(
   Priority_Aggregation *aggregation,
   Priority_Node        *node
@@ -153,6 +245,14 @@ RTEMS_INLINE_ROUTINE void _Priority_Initialize_one(
   _RBTree_Initialize_one( &aggregation->Contributors, &node->Node.RBTree );
 }
 
+/**
+ * @brief Checks if the priority aggregation is empty.
+ *
+ * @param aggregation The priority aggregation that shall be verified if it is empty.
+ *
+ * @retval true The priority aggregation is empty.
+ * @retval false The priority aggregation is not empty.
+ */
 RTEMS_INLINE_ROUTINE bool _Priority_Is_empty(
   const Priority_Aggregation *aggregation
 )
@@ -160,6 +260,13 @@ RTEMS_INLINE_ROUTINE bool _Priority_Is_empty(
   return _RBTree_Is_empty( &aggregation->Contributors );
 }
 
+/**
+ * @brief Gets the priority aggregation's priority.
+ *
+ * @param aggregation The priority aggregation to get the priority from.
+ *
+ * @return The priority of @a aggregation.
+ */
 RTEMS_INLINE_ROUTINE Priority_Control _Priority_Get_priority(
   const Priority_Aggregation *aggregation
 )
@@ -167,6 +274,13 @@ RTEMS_INLINE_ROUTINE Priority_Control _Priority_Get_priority(
   return aggregation->Node.priority;
 }
 
+/**
+ * @brief Gets the priority aggregation's scheduler.
+ *
+ * @param aggregation The priority aggregation to get the scheduler from.
+ *
+ * @return The scheduler of @a aggregation.
+ */
 RTEMS_INLINE_ROUTINE const Scheduler_Control *_Priority_Get_scheduler(
   const Priority_Aggregation *aggregation
 )
@@ -178,6 +292,13 @@ RTEMS_INLINE_ROUTINE const Scheduler_Control *_Priority_Get_scheduler(
 #endif
 }
 
+/**
+ * @brief Gets the minimum node of the priority aggregation
+ *
+ * @param aggregation The priority aggregation to get the minimum node from.
+ *
+ * @return The minimum node of @a aggregation
+ */
 RTEMS_INLINE_ROUTINE Priority_Node *_Priority_Get_minimum_node(
   const Priority_Aggregation *aggregation
 )
@@ -185,6 +306,12 @@ RTEMS_INLINE_ROUTINE Priority_Node *_Priority_Get_minimum_node(
   return (Priority_Node *) _RBTree_Minimum( &aggregation->Contributors );
 }
 
+/**
+ * @brief Sets the action node of the priority aggregation.
+ *
+ * @param[out] aggregation The priority aggregation to set the action node of.
+ * @param node The new priority node for @a aggregation.
+ */
 RTEMS_INLINE_ROUTINE void _Priority_Set_action_node(
   Priority_Aggregation *aggregation,
   Priority_Node        *node
@@ -193,6 +320,12 @@ RTEMS_INLINE_ROUTINE void _Priority_Set_action_node(
   aggregation->Action.node = node;
 }
 
+/**
+ * @brief Sets the action type of the priority aggregation.
+ *
+ * @param[out] aggregation The priority aggregation to set the action type of.
+ * @param type The new action type for @a aggregation.
+ */
 RTEMS_INLINE_ROUTINE void _Priority_Set_action_type(
   Priority_Aggregation *aggregation,
   Priority_Action_type  type
@@ -201,6 +334,14 @@ RTEMS_INLINE_ROUTINE void _Priority_Set_action_type(
   aggregation->Action.type = type;
 }
 
+/**
+ * @brief Sets the action type and action node of the priority aggregation.
+ *
+ * @param[out] aggregation The priority aggregation to set the action type
+ *      and action node of.
+ * @param node The new action node for @a aggregation.
+ * @param type The new action type for @a aggregation.
+ */
 RTEMS_INLINE_ROUTINE void _Priority_Set_action(
   Priority_Aggregation *aggregation,
   Priority_Node        *node,
@@ -211,6 +352,14 @@ RTEMS_INLINE_ROUTINE void _Priority_Set_action(
   aggregation->Action.type = type;
 }
 
+/**
+ * @brief Gets the next action of the priority aggregation.
+ *
+ * @param aggregation The priority aggregation to get the next action of.
+ *
+ * @retval next_action The next action of @a aggregation if RTEMS_SMP is defined.
+ * @retval NULL RTEMS_SMP is not defined.
+ */
 RTEMS_INLINE_ROUTINE Priority_Aggregation *_Priority_Get_next_action(
   const Priority_Aggregation *aggregation
 )
@@ -223,6 +372,15 @@ RTEMS_INLINE_ROUTINE Priority_Aggregation *_Priority_Get_next_action(
 #endif
 }
 
+/**
+ * @brief Compares two priorities.
+ *
+ * @param left The priority control on the left hand side of the comparison.
+ * @param right THe RBTree_Node to get the priority for the comparison from.
+ *
+ * @retval true The priority on the left hand side of the comparison is smaller.
+ * @retval false The priority on the left hand side of the comparison is greater of equal.
+ */
 RTEMS_INLINE_ROUTINE bool _Priority_Less(
   const void        *left,
   const RBTree_Node *right
@@ -237,6 +395,19 @@ RTEMS_INLINE_ROUTINE bool _Priority_Less(
   return *the_left < the_right->priority;
 }
 
+/**
+ * @brief Inserts the node with the given priority into the
+ *      priority aggregation's contributors.
+ *
+ * This method does not handle the case that @a node was the minimal node.
+ *
+ * @param[in, out] aggregation The aggregation to insert the node in its contributors.
+ * @param[in] node The node to insert in the contributors.
+ * @param priority The priority control for the inserted node.
+ *
+ * @retval true The inserted node with its priority is the minimum of the RBTree.
+ * @retval false The inserted node with its priority is not the minimum of the RBTree.
+ */
 RTEMS_INLINE_ROUTINE bool _Priority_Plain_insert(
   Priority_Aggregation *aggregation,
   Priority_Node        *node,
@@ -251,6 +422,14 @@ RTEMS_INLINE_ROUTINE bool _Priority_Plain_insert(
   );
 }
 
+/**
+ * @brief Extracts the priority node from the aggregation.
+ *
+ * This method does not handle the case that @a node was the minimal node.
+ *
+ * @param[in,  out] aggregation The aggregation to extract the node from.
+ * @param node The node to be extracted.
+ */
 RTEMS_INLINE_ROUTINE void _Priority_Plain_extract(
   Priority_Aggregation *aggregation,
   Priority_Node        *node
@@ -259,6 +438,15 @@ RTEMS_INLINE_ROUTINE void _Priority_Plain_extract(
   _RBTree_Extract( &aggregation->Contributors, &node->Node.RBTree );
 }
 
+/**
+ * @brief Updates the priority of the node in the aggregation.
+ *
+ * It first extracts the node and inserts it again, with the new @a node priority as key.
+ *   This method does not handle the case that @a node was the minimal node.
+ *
+ * @param[in, out] aggregation The aggregation to change the node in.
+ * @param node The node that has a new priority and will be reinserted in the aggregation.
+ */
 RTEMS_INLINE_ROUTINE void _Priority_Plain_changed(
   Priority_Aggregation *aggregation,
   Priority_Node        *node
@@ -287,6 +475,16 @@ typedef void ( *Priority_Remove_handler )(
   void                 *arg
 );
 
+/**
+ * @brief Does nothing.
+ *
+ * This method does nothing.
+ *
+ * @param aggregation Is ignored by the method.
+ * @param prepend_it Is ignored by the method.
+ * @param actions Is ignored by the method.
+ * @param arg Is ignored by the method.
+ */
 RTEMS_INLINE_ROUTINE void _Priority_Change_nothing(
   Priority_Aggregation *aggregation,
   bool                  prepend_it,
@@ -300,6 +498,15 @@ RTEMS_INLINE_ROUTINE void _Priority_Change_nothing(
   (void) arg;
 }
 
+/**
+ * @brief Does nothing.
+ *
+ * This method does nothing.
+ *
+ * @param aggregation Is ignored by the method.
+ * @param actions Is ignored by the method.
+ * @param arg Is ignored by the method.
+ */
 RTEMS_INLINE_ROUTINE void _Priority_Remove_nothing(
   Priority_Aggregation *aggregation,
   Priority_Actions     *actions,
@@ -311,6 +518,19 @@ RTEMS_INLINE_ROUTINE void _Priority_Remove_nothing(
   (void) arg;
 }
 
+/**
+ * @brief Inserts the node in a nonempty aggregation and handles change if
+ *      the node is the new minimum.
+ *
+ * @param[in, out] aggregation The aggregation to insert the node into.
+ * @param node The node to be inserted.  The node's priority is used as a key.
+ * @param actions Parameter for @a change that is used if the node is the new
+ *      minimum.
+ * @param change The priority change handler that is called in the case that
+ *      the new node is the minimum of the aggregation.
+ * @param arg Arguments for @a change that is used if the node is the new
+ *      minimum.
+ */
 RTEMS_INLINE_ROUTINE void _Priority_Non_empty_insert(
   Priority_Aggregation    *aggregation,
   Priority_Node           *node,
@@ -330,6 +550,18 @@ RTEMS_INLINE_ROUTINE void _Priority_Non_empty_insert(
   }
 }
 
+/**
+ * @brief
+ *
+ * @param[in, out] aggregation The aggregation to insert the node in.
+ * @param node The node to be inserted.  The node's priority is used as key.
+ * @param actions Priority actions for the case that the aggregation was empty before
+ *      the insert or the node is the new minimum.
+ * @param add Is called in the case that @a aggregation was empty before the insert.
+ * @param change Is called in the case that @a aggregation was nonempty before the
+ *      insert and @a node is the new minimum of the aggregation.
+ * @param arg The arguments for @a change.
+ */
 RTEMS_INLINE_ROUTINE void _Priority_Insert(
   Priority_Aggregation    *aggregation,
   Priority_Node           *node,
@@ -347,6 +579,23 @@ RTEMS_INLINE_ROUTINE void _Priority_Insert(
   }
 }
 
+/**
+ * @brief Extracts the node from the aggregation.
+ *
+ * This method extracts the node from the aggregation and handles the
+ * cases that @a aggregation is empty after the extraction, or that
+ * @a node was the minimal node in @a aggregation by calling remove (if
+ * empty) or change (if @a node was the minimal node).
+ *
+ * @param[in, out] aggregation The aggregation to extract the @a node from.
+ * @param node The node to extract from @a aggregation.
+ * @param actions The actions for the cases that the aggregation is empty
+ *      after the extraction, or the minimal node was extracted.
+ * @param remove Is called in the case that the aggregation is empty after
+ *      the extraction.
+ * @param change Is called in the case that the minimal node was extracted.
+ * @param arg The arguments for @a remove and @a change.
+ */
 RTEMS_INLINE_ROUTINE void _Priority_Extract(
   Priority_Aggregation    *aggregation,
   Priority_Node           *node,
@@ -372,6 +621,19 @@ RTEMS_INLINE_ROUTINE void _Priority_Extract(
   }
 }
 
+/**
+ * @brief Extracts the node from the aggregation.
+ *
+ * This method extracts the node from the aggregation and handles the
+ * case that @a node was the minimal node in @a aggregation by calling
+ * change (if @a node was the minimal node).
+ *
+ * @param[in, out] aggregation The aggregation to extract the @a node from.
+ * @param node The node to extract from @a aggregation.
+ * @param actions The actions for the case that the minimal node was extracted.
+ * @param change Is called in the case that the minimal node was extracted.
+ * @param arg The arguments for @a change.
+ */
 RTEMS_INLINE_ROUTINE void _Priority_Extract_non_empty(
   Priority_Aggregation    *aggregation,
   Priority_Node           *node,
@@ -393,6 +655,21 @@ RTEMS_INLINE_ROUTINE void _Priority_Extract_non_empty(
   }
 }
 
+/**
+ * @brief Updates the priority of the node in the aggregation.
+ *
+ * This method handles the case that @a node was the minimal node in
+ * @a aggregation.
+ *
+ * @param[in, out] aggregation The aggregation to change the node in.
+ * @param node The node that has a new priority and will be reinserted in the aggregation.
+ * @param prepend_it Indicates whether @a change should prepend if the minimal priority is
+ *      incorrectly set after the change.
+ * @param actions The actions for the case that the minimal priority is incorrectly set
+ *      after the change.
+ * @param change Is called if the minimal priority is incorrectly set after the change.
+ * @param arg The arguments for @a change.
+ */
 RTEMS_INLINE_ROUTINE void _Priority_Changed(
   Priority_Aggregation    *aggregation,
   Priority_Node           *node,
@@ -414,6 +691,16 @@ RTEMS_INLINE_ROUTINE void _Priority_Changed(
   }
 }
 
+/**
+ * @brief Replaces one node by another.
+ *
+ * The new node has the priority of the old node.
+ *
+ * @param[in, out] aggregation The aggregation to replace @a victim by @a replacement in.
+ * @param victim The node that will be replaced.
+ * @param[out] replacement The node that replaces @a victim.  It obtains its priority
+ *      from @a victim.
+ */
 RTEMS_INLINE_ROUTINE void _Priority_Replace(
   Priority_Aggregation *aggregation,
   Priority_Node        *victim,
@@ -428,6 +715,8 @@ RTEMS_INLINE_ROUTINE void _Priority_Replace(
   );
 }
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif /* __cplusplus */