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

Update #3706.

cpukit/include/rtems/score/schedulercbs.h

@@ -1,6 +1,8 @@
 /**
  * @file
  *
+ * @ingroup RTEMSScoreSchedulerCBS
+ *
  * @brief Thread manipulation for the CBS scheduler
  *
  * This include file contains all the constants and structures associated
@@ -36,8 +38,11 @@ extern "C" {
  * @defgroup RTEMSScoreSchedulerCBS CBS Scheduler
  *
  * @ingroup RTEMSScoreScheduler
+ *
+ * @brief CBS Scheduler.
+ *
+ * @{
  */
-/**@{*/
 
 #define SCHEDULER_CBS_MAXIMUM_PRIORITY SCHEDULER_EDF_MAXIMUM_PRIORITY
 
@@ -146,12 +151,28 @@ typedef struct {
  */
 extern Scheduler_CBS_Server _Scheduler_CBS_Server_list[];
 
+/**
+ * @brief Unblocks a thread.
+ *
+ * @param scheduler The scheduler control.
+ * @param the_thread The thread to unblock.
+ * @param node The scheduler node.
+ */
 void _Scheduler_CBS_Unblock(
   const Scheduler_Control *scheduler,
   Thread_Control          *the_thread,
   Scheduler_Node          *node
 );
 
+/**
+ * @brief Releases a job.
+ *
+ * @param scheduler The scheduler for the operation.
+ * @param the_thread The corresponding thread.
+ * @param priority_node The priority node for the operation.
+ * @param deadline The deadline for the job.
+ * @param queue_context The thread queue context.
+ */
 void _Scheduler_CBS_Release_job(
   const Scheduler_Control *scheduler,
   Thread_Control          *the_thread,
@@ -160,6 +181,14 @@ void _Scheduler_CBS_Release_job(
   Thread_queue_Context    *queue_context
 );
 
+/**
+ * @brief Cancels a job.
+ *
+ * @param scheduler The scheduler for the operation.
+ * @param the_thread The corresponding thread.
+ * @param priority_node The priority node for the operation.
+ * @param queue_context The thread queue context.
+ */
 void _Scheduler_CBS_Cancel_job(
   const Scheduler_Control *scheduler,
   Thread_Control          *the_thread,
@@ -172,16 +201,23 @@ void _Scheduler_CBS_Cancel_job(
  *
  * Initializes the CBS library.
  *
- *  @retval status code.
+ * @return SCHEDULER_CBS_OK This method always returns this status.
  */
 int _Scheduler_CBS_Initialize(void);
 
 /**
- *  @brief Attach a task to an already existing server.
+ * @brief Attaches a task to an already existing server.
  *
  * Attach a task to an already existing server.
  *
- *  @retval status code.
+ * @param server_id The id of the existing server.
+ * @param task_id The id of the task to attach.
+ *
+ * @retval SCHEDULER_CBS_OK The operation was successful.
+ * @retval SCHEDULER_CBS_ERROR_INVALID_PARAMETER The server id is so big
+ *      or there is no thread for this task id.
+ * @retval SCHEDULER_CBS_ERROR_NOSERVER The server is not yet initialized.
+ * @retval SCHEDULER_CBS_ERROR_FULL The server already has a task.
  */
 int _Scheduler_CBS_Attach_thread (
   Scheduler_CBS_Server_id server_id,
@@ -189,11 +225,18 @@ int _Scheduler_CBS_Attach_thread (
 );
 
 /**
- *  @brief Detach from the CBS Server.
+ * @brief Detaches from the CBS Server.
  *
  * Detach from the CBS Server.
  *
- *  @retval status code.
+ * @param server_id The id of the existing server.
+ * @param task_id The id of the task to attach.
+ *
+ * @retval SCHEDULER_CBS_OK The operation was successful.
+ * @retval SCHEDULER_CBS_ERROR_INVALID_PARAMETER The server id is to big,
+ *      or the task with this id is not attached to this server or there is
+ *      no thread with this task.
+ * @retval SCHEDULER_CBS_ERROR_NOSERVER The server is not yet initialized.
  */
 int _Scheduler_CBS_Detach_thread (
   Scheduler_CBS_Server_id server_id,
@@ -201,20 +244,28 @@ int _Scheduler_CBS_Detach_thread (
 );
 
 /**
- *  @brief Cleanup resources associated to the CBS Library.
+ * @brief Cleans up resources associated to the CBS Library.
  *
  * Cleanup resources associated to the CBS Library.
  *
- *  @retval status code.
+ * @return This method always returns SCHEDULER_CBS_OK.
  */
 int _Scheduler_CBS_Cleanup (void);
 
 /**
- *  @brief Create a new server with specified parameters.
+ * @brief Creates a new server with specified parameters.
  *
  * Create a new server with specified parameters.
  *
- *  @retval status code.
+ * @param params The parameters for the server.
+ * @param budget_overrun_callback The budget overrun for the new server.
+ * @param[out] server_id In the case of success, this parameter contains the
+ *      id of the newly created server.
+ *
+ * @retval SCHEDULER_CBS_OK The operation succeeded.
+ * @retval SCHEDULER_CBS_ERROR_INVALID_PARAMETER The given parameters are invalid.
+ * @retval SCHEDULER_CBS_ERROR_FULL The maximum number of servers was already
+ *      created, a new server cannot be created.
  */
 int _Scheduler_CBS_Create_server (
   Scheduler_CBS_Parameters     *params,
@@ -223,25 +274,32 @@ int _Scheduler_CBS_Create_server (
 );
 
 /**
- *  @brief Detach all tasks from a server and destroy it.
+ * @brief Detaches all tasks from a server and destroys it.
  *
  * Detach all tasks from a server and destroy it.
  *
- *  @param[in] server_id is the ID of the server
+ * @param server_id The id of the server to destroy.
  *
- *  @retval status code.
+ * @retval SCHEDULER_CBS_OK The operation was successful.
+ * @retval SCHEDULER_CBS_ERROR_INVALID_PARAMETER The server id is too big.
+ * @retval SCHEDULER_CBS_ERROR_NOSERVER There is no initialized server with this id.
  */
 int _Scheduler_CBS_Destroy_server (
   Scheduler_CBS_Server_id server_id
 );
 
 /**
- *  @brief Retrieve the approved budget.
+ * @brief Retrieves the approved budget.
  *
  * Retrieve the budget that has been approved for the subsequent
  * server instances.
  *
- *  @retval status code.
+ * @param server_id The id of the server instance of which the budget is wanted.
+ * @param[out] approved_budget Contains the approved budget after a successful method call.
+ *
+ * @retval SCHEDULER_CBS_OK The operation was successful.
+ * @retval SCHEDULER_CBS_ERROR_INVALID_PARAMETER The server id is too big.
+ * @retval SCHEDULER_CBS_ERROR_NOSERVER There is no initialized server with this id.
  */
 int _Scheduler_CBS_Get_approved_budget (
   Scheduler_CBS_Server_id  server_id,
@@ -249,11 +307,16 @@ int _Scheduler_CBS_Get_approved_budget (
 );
 
 /**
- *  @brief Retrieve remaining budget for the current server instance.
+ * @brief Retrieves remaining budget for the current server instance.
  *
  * Retrieve remaining budget for the current server instance.
  *
- *  @retval status code.
+ * @param server_id The id of the server instance of which the remaining budget is wanted.
+ * @param[out] remaining_budget Contains the remaining budget after a successful method call.
+ *
+ * @retval SCHEDULER_CBS_OK The operation was successful.
+ * @retval SCHEDULER_CBS_ERROR_INVALID_PARAMETER The server id is too big.
+ * @retval SCHEDULER_CBS_ERROR_NOSERVER There is no initialized server with this id.
  */
 int _Scheduler_CBS_Get_remaining_budget (
   Scheduler_CBS_Server_id  server_id,
@@ -261,15 +324,17 @@ int _Scheduler_CBS_Get_remaining_budget (
 );
 
 /**
- *  @brief Get relative time info.
+ * @brief Gets relative time info.
  *
  * Retrieve time info relative to @a server_id. The server status code is returned.
  *
- *  @param[in] server_id is the server to get the status code from.
+ * @param server_id is the server to get the status code from.
- *  @param[in] exec_time is the execution time.
+ * @param[out] exec_time Contains the execution time after a successful method call.
- *  @param[in] abs_time is not apparently used.
+ * @param abs_time Not apparently used.
  *
- *  @retval status code.
+ * @retval SCHEDULER_CBS_OK The operation was successful.
+ * @retval SCHEDULER_CBS_ERROR_INVALID_PARAMETER The server id is too big.
+ * @retval SCHEDULER_CBS_ERROR_NOSERVER There is no initialized server with this id.
  */
 int _Scheduler_CBS_Get_execution_time (
   Scheduler_CBS_Server_id   server_id,
@@ -278,11 +343,16 @@ int _Scheduler_CBS_Get_execution_time (
 );
 
 /**
- *  @brief Retrieve CBS scheduling parameters.
+ * @brief Retrieves CBS scheduling parameters.
  *
  * Retrieve CBS scheduling parameters.
  *
- *  @retval status code.
+ * @param server_id The id of the server to get the scheduling parameters from.
+ * @param[out] params Will contain the scheduling parameters after successful method call.
+ *
+ * @retval SCHEDULER_CBS_OK The operation was successful.
+ * @retval SCHEDULER_CBS_ERROR_INVALID_PARAMETER The server id is too big.
+ * @retval SCHEDULER_CBS_ERROR_NOSERVER There is no initialized server with this id.
  */
 int _Scheduler_CBS_Get_parameters (
   Scheduler_CBS_Server_id   server_id,
@@ -290,12 +360,15 @@ int _Scheduler_CBS_Get_parameters (
 );
 
 /**
- *  @brief Get a thread server id.
+ * @brief Gets a thread server id.
  *
  * Get a thread server id, or SCHEDULER_CBS_ERROR_NOT_FOUND if it is not
  * attached to any server.
  *
- *  @retval status code.
+ * @param task_id The id of the task to get the corresponding server.
+ * @param[out] server_id Will contain the server id after successful method call.
+ * @retval SCHEDULER_CBS_OK The operation was successful
+ * @retval SCHEDULER_CBS_ERROR_NOSERVER There is no server with this task attached.
  */
 int _Scheduler_CBS_Get_server_id (
   rtems_id                 task_id,
@@ -303,14 +376,17 @@ int _Scheduler_CBS_Get_server_id (
 );
 
 /**
- *  @brief Set parameters for CBS scheduling.
+ * @brief Sets parameters for CBS scheduling.
  *
  * Change CBS scheduling parameters.
  *
- *  @param[in] server_id is the ID of the server.
+ * @param server_id The id of the server.
- *  @param[in] parameters are the parameters to set.
+ * @param parameters The parameters to set.
  *
- *  @retval status code.
+ * @retval SCHEDULER_CBS_OK The operation was successful.
+ * @retval SCHEDULER_CBS_ERROR_INVALID_PARAMETER The server id is too big or the
+ *      given parameters are invalid.
+ * @retval SCHEDULER_CBS_ERROR_NOSERVER There is no server with this id.
  */
 int _Scheduler_CBS_Set_parameters (
   Scheduler_CBS_Server_id   server_id,
@@ -321,6 +397,8 @@ int _Scheduler_CBS_Set_parameters (
  * @brief Invoked when a limited time quantum is exceeded.
  *
  * This routine is invoked when a limited time quantum is exceeded.
+ *
+ * @param the_thread The thread that exceeded a limited time quantum.
  */
 void _Scheduler_CBS_Budget_callout(
   Thread_Control *the_thread
@@ -328,6 +406,11 @@ void _Scheduler_CBS_Budget_callout(
 
 /**
  * @brief Initializes a CBS specific scheduler node of @a the_thread.
+ *
+ * @param scheduler The scheduler control for the operation.
+ * @param[out] node The scheduler node to initalize.
+ * @param the_thread The thread to initialize a scheduler node for.
+ * @param priority The priority for the node.
  */
 void _Scheduler_CBS_Node_initialize(
   const Scheduler_Control *scheduler,
@@ -340,7 +423,7 @@ void _Scheduler_CBS_Node_initialize(
 }
 #endif
 
-/**@}*/
+/** @} */
 
 #endif
 /* end of include file */