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

Update #3706.

1 files changed, 94 insertions, 76 deletions

diff --git a/cpukit/include/rtems/score/objectmp.h b/cpukit/include/rtems/score/objectmp.h
index c32d88545b..fcdfa78aa3 100644
--- a/cpukit/include/rtems/score/objectmp.h
+++ b/cpukit/include/rtems/score/objectmp.h
@@ -1,10 +1,12 @@
 /**
- *  @file
+ * @file
  *
- *  @brief Data Associated with the Manipulation of Global RTEMS Objects
+ * @ingroup RTEMSScoreObjectMP
  *
- *  This include file contains all the constants and structures associated
- *  with the manipulation of Global RTEMS Objects.
+ * @brief Data Associated with the Manipulation of Global RTEMS Objects
+ *
+ * This include file contains all the constants and structures associated
+ * with the manipulation of Global RTEMS Objects.
  */
 
 /*
@@ -30,49 +32,52 @@ extern "C" {
 #endif
 
 /**
- *  @defgroup RTEMSScoreObjectMP Object Handler Multiprocessing Support
+ * @defgroup RTEMSScoreObjectMP Object Handler Multiprocessing Support
+ *
+ * @ingroup RTEMSScore
+ *
+ * @brief Object Handler Multiprocessing Support
  *
- *  @ingroup RTEMSScore
+ * This handler encapsulates functionality which is used to manage
+ * objects which have been declared to be globally visible.  This handler
+ * knows objects from all of the nodes in the system.
  *
- *  This handler encapsulates functionality which is used to manage
- *  objects which have been declared to be globally visible.  This handler
- *  knows objects from all of the nodes in the system.
+ * @{
  */
-/**@{*/
 
 /**
- *  @brief Intializes the inactive global object chain
- *  based on the maximum number of global objects configured.
+ * @brief Intializes the inactive global object chain
+ * based on the maximum number of global objects configured.
  *
- *  This routine intializes the inactive global object chain
- *  based on the maximum number of global objects configured.
+ * This routine intializes the inactive global object chain
+ * based on the maximum number of global objects configured.
  */
 void _Objects_MP_Handler_initialization(void);
 
 /**
- *  @brief Intializes the global object node number
- *  used in the ID field of all objects.
+ * @brief Intializes the global object node number
+ * used in the ID field of all objects.
  *
- *  This routine intializes the global object node number
- *  used in the ID field of all objects.
+ * This routine intializes the global object node number
+ * used in the ID field of all objects.
  */
 void _Objects_MP_Handler_early_initialization(void);
 
 /**
- *  @brief Place the specified global object in the
- *  specified information table.
+ * @brief Place the specified global object in the
+ * specified information table.
  *
- *  This routine place the specified global object in the
- *  specified information table.
+ * This routine place the specified global object in the
+ * specified information table.
  *
- *  @param[in] information points to the object information table for this
- *             object class.
- *  @param[in] the_global_object points to the object being opened.
- *  @param[in] the_name is the name of the object being opened.
- *  @param[in] the_id is the Id of the object being opened.
+ * @param[in, out] information Points to the object information table for this
+ *            object class.
+ * @param[in, out] the_global_object Points to the object being opened.
+ * @param the_name The name of the object being opened.
+ * @param the_id The Id of the object being opened.
  *
- *  @todo This method only works for object types with 4 byte object names.
- *        It does not support variable length object names.
+ * @todo This method only works for object types with 4 byte object names.
+ *       It does not support variable length object names.
  */
 void _Objects_MP_Open (
   Objects_Information *information,
@@ -82,23 +87,26 @@ void _Objects_MP_Open (
 );
 
 /**
- *  @brief  Allocates a global object control block
- *  and places it in the specified information table.
- *
- *  This routine allocates a global object control block
- *  and places it in the specified information table.  If the
- *  allocation fails, then is_fatal_error determines the
- *  error processing actions taken.
- *
- *  @param[in] information points to the object information table for this
- *             object class.
- *  @param[in] the_name is the name of the object being opened.
- *  @param[in] the_id is the Id of the object being opened.
- *  @param[in] is_fatal_error is true if not being able to allocate the
- *             object is considered a fatal error.
- *
- *  @todo This method only works for object types with 4 byte object names.
- *        It does not support variable length object names.
+ * @brief  Allocates a global object control block
+ * and places it in the specified information table.
+ *
+ * This routine allocates a global object control block
+ * and places it in the specified information table.  If the
+ * allocation fails, then is_fatal_error determines the
+ * error processing actions taken.
+ *
+ * @param[in, out] information Points to the object information table for this
+ *            object class.
+ * @param the_name The name of the object being opened.
+ * @param the_id The Id of the object being opened.
+ * @param is_fatal_error Indicates whether not being able to allocate the
+ *            object is considered a fatal error.
+ *
+ * @retval true The operation succeeded.
+ * @retval false The allocation failed, but @a is_fatal_error was set to false.
+ *
+ * @todo This method only works for object types with 4 byte object names.
+ *       It does not support variable length object names.
  */
 bool _Objects_MP_Allocate_and_open (
   Objects_Information *information,
@@ -108,10 +116,14 @@ bool _Objects_MP_Allocate_and_open (
 );
 
 /**
- *  @brief Removes a global object from the specified information table.
+ * @brief Removes a global object from the specified information table.
  *
- *  This routine removes a global object from the specified
- *  information table and deallocates the global object control block.
+ * This routine removes a global object from the specified
+ * information table and deallocates the global object control block.
+ *
+ * @param[in, out] information Points to the object information table for this
+ *            object class.
+ * @param the_id The id of the global object to remove.
  */
 void _Objects_MP_Close (
   Objects_Information *information,
@@ -119,22 +131,23 @@ void _Objects_MP_Close (
 );
 
 /**
- *  @brief Look for the object with the_name in the global
- *  object tables indicated by information.
- *
- *  This routine looks for the object with the_name in the global
- *  object tables indicated by information.  It returns the ID of the
- *  object with that name if one is found.
- *
- *  @param[in] information points to the object information table for this
- *             object class.
- *  @param[in] the_name is the name of the object being searched for.
- *  @param[in] nodes_to_search indicates the set of nodes to search.
- *  @param[in] the_id will contain the Id of the object if found.
- *
- *  @retval This method returns one of the
- *          @ref Objects_Name_or_id_lookup_errors.  If successful, @a the_id
- *          will contain the Id of the object.
+ * @brief Looks for the object with the_name in the global
+ * object tables indicated by information.
+ *
+ * This routine looks for the object with the_name in the global
+ * object tables indicated by information.  It returns the ID of the
+ * object with that name if one is found.
+ *
+ * @param information Points to the object information table for this
+ *            object class.
+ * @param the_name The name of the object being searched for.
+ * @param nodes_to_search Indicates the set of nodes to search.
+ * @param[out] the_id will contain the Id of the object if found.
+ *
+ * @retval OBJECTS_NAME_OR_ID_LOOKUP_SUCCESSFUL The lookup was successful.
+ * @retval OBJECTS_INVALID_NODE The number of nodes is bigger than the
+ *      objects maximum nodes value.
+ * @retval OBJECTS_INVALID_NAME There is no global object with this name.
  */
 Objects_Name_or_id_lookup_errors _Objects_MP_Global_name_search (
   Objects_Information *information,
@@ -144,15 +157,16 @@ Objects_Name_or_id_lookup_errors _Objects_MP_Global_name_search (
 );
 
 /**
- * @brief Returns true, if the object identifier is in the global object
- * identifier cache of the specified object information, otherwise false.
+ * @brief Checks if the object identifier is in the global object
+ * identifier cache of the specified object information.
  *
  * @param id The object identifier.
  * @param information The object information.
  *
- * @retval true A remote objects with this object identifier exits in the
+ * @retval true A remote objects with this object identifier exists in the
+ * global object identifier cache of the specified information.
+ * @retval false A remote objects with this object identifier does not exist in the
  * global object identifier cache of the specified information.
- * @retval false Otherwise.
  */
 bool _Objects_MP_Is_remote(
   Objects_Id                 id,
@@ -165,21 +179,25 @@ bool _Objects_MP_Is_remote(
 extern uint32_t _Objects_MP_Maximum_global_objects;
 
 /**
- * This function allocates a Global Object control block.
+ * @brief This function allocates a Global Object control block.
  */
-
 Objects_MP_Control *_Objects_MP_Allocate_global_object( void );
 
 /**
- * This routine deallocates a Global Object control block.
+ * @brief This routine deallocates a Global Object control block.
+ *
+ * @param[out] the_object The object to deallocate.
  */
-
 void _Objects_MP_Free_global_object( Objects_MP_Control *the_object );
 
 /**
- * This function returns whether the global object is NULL or not.
+ * @brief Checks if the global object is NULL or not.
+ *
+ * @param the_object The object to check if it is NULL.
+ *
+ * @retval true @a the_object is NULL.
+ * @retval false @a the_object is not NULL.
  */
-
 RTEMS_INLINE_ROUTINE bool _Objects_MP_Is_null_global_object (
   Objects_MP_Control *the_object
 )
@@ -187,7 +205,7 @@ RTEMS_INLINE_ROUTINE bool _Objects_MP_Is_null_global_object (
   return( the_object == NULL );
 }
 
-/**@}*/
+/** @} */
 
 #ifdef __cplusplus
 }