[PATCH 34/98] doxygen: score: adjust doc in objectmp.h to doxygen guidelines
Sebastian Huber
sebastian.huber at embedded-brains.de
Tue May 7 05:39:39 UTC 2019
From: Andreas Dachsberger <andreas.dachsberger at embedded-brains.de>
---
cpukit/include/rtems/score/objectmp.h | 170 +++++++++++++++++++---------------
1 file 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
}
--
2.16.4
More information about the devel
mailing list