From 6a074363a2657a86b5f1ea0fc1185f68ad9f3c08 Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Mon, 16 Jan 2006 15:13:58 +0000 Subject: 2006-01-16 Joel Sherrill Large patch to improve Doxygen output. As a side-effect, grammar and spelling errors were corrected, spacing errors were address, and some variable names were improved. * libmisc/monitor/mon-object.c, libmisc/monitor/monitor.h: Account for changing OBJECTS_NO_CLASS to OBJECTS_CLASSIC_NO_CLASS. * score/Doxyfile: Set output directory. Predefine some macro values. Turn on graphical output. * score/include/rtems/debug.h, score/include/rtems/seterr.h, score/include/rtems/system.h, score/include/rtems/score/address.h, score/include/rtems/score/apiext.h, score/include/rtems/score/apimutex.h, score/include/rtems/score/bitfield.h, score/include/rtems/score/chain.h, score/include/rtems/score/context.h, score/include/rtems/score/coremsg.h, score/include/rtems/score/coremutex.h, score/include/rtems/score/coresem.h, score/include/rtems/score/heap.h, score/include/rtems/score/interr.h, score/include/rtems/score/isr.h, score/include/rtems/score/mpci.h, score/include/rtems/score/mppkt.h, score/include/rtems/score/object.h, score/include/rtems/score/objectmp.h, score/include/rtems/score/priority.h, score/include/rtems/score/stack.h, score/include/rtems/score/states.h, score/include/rtems/score/sysstate.h, score/include/rtems/score/thread.h, score/include/rtems/score/threadmp.h, score/include/rtems/score/threadq.h, score/include/rtems/score/tod.h, score/include/rtems/score/tqdata.h, score/include/rtems/score/userext.h, score/include/rtems/score/watchdog.h, score/include/rtems/score/wkspace.h, score/inline/rtems/score/address.inl, score/inline/rtems/score/chain.inl, score/inline/rtems/score/coremutex.inl, score/inline/rtems/score/coresem.inl, score/inline/rtems/score/heap.inl, score/inline/rtems/score/object.inl, score/inline/rtems/score/stack.inl, score/inline/rtems/score/thread.inl, score/inline/rtems/score/tqdata.inl, score/macros/README, score/src/heap.c, score/src/threadmp.c, score/src/threadready.c, score/src/threadstartmultitasking.c: Improve generated Doxygen output. Fix spelling and grammar errors in comments. Correct names of some variables and propagate changes. --- cpukit/score/inline/rtems/score/object.inl | 185 +++++++++++++---------------- 1 file changed, 83 insertions(+), 102 deletions(-) (limited to 'cpukit/score/inline/rtems/score/object.inl') diff --git a/cpukit/score/inline/rtems/score/object.inl b/cpukit/score/inline/rtems/score/object.inl index ac6d873fc8..e3e17bdb69 100644 --- a/cpukit/score/inline/rtems/score/object.inl +++ b/cpukit/score/inline/rtems/score/object.inl @@ -7,7 +7,7 @@ * This include file contains the static inline implementation of all * of the inlined routines in the Object Handler. * - * COPYRIGHT (c) 1989-2002. + * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -20,16 +20,18 @@ #ifndef _RTEMS_SCORE_OBJECT_INL #define _RTEMS_SCORE_OBJECT_INL -/*PAGE - * - * _Objects_Build_id - * - * DESCRIPTION: - * +/** * This function builds an object's id from the processor node and index * values specified. + * + * @param[in] the_api indicates the API associated with this Id. + * @param[in] the_class indicates the class of object. + * It is specific to @a the_api. + * @param[in] node is the node where this object resides. + * @param[in] index is the instance number of this object. + * + * @return This method returns an object Id constructed from the arguments. */ - RTEMS_INLINE_ROUTINE Objects_Id _Objects_Build_id( Objects_APIs the_api, uint32_t the_class, @@ -43,15 +45,13 @@ RTEMS_INLINE_ROUTINE Objects_Id _Objects_Build_id( (( (Objects_Id) index ) << OBJECTS_INDEX_START_BIT); } -/*PAGE - * - * _Objects_Get_API +/** + * This function returns the API portion of the ID. * - * DESCRIPTION: + * @param[in] id is the object Id to be processed. * - * This function returns the API portion of the ID. + * @return This method returns an object Id constructed from the arguments. */ - RTEMS_INLINE_ROUTINE Objects_APIs _Objects_Get_API( Objects_Id id ) @@ -59,15 +59,11 @@ RTEMS_INLINE_ROUTINE Objects_APIs _Objects_Get_API( return (Objects_APIs) ((id >> OBJECTS_API_START_BIT) & OBJECTS_API_VALID_BITS); } -/*PAGE - * - * _Objects_Get_class - * - * DESCRIPTION: - * +/** * This function returns the class portion of the ID. + * + * @param[in] id is the object Id to be processed */ - RTEMS_INLINE_ROUTINE uint32_t _Objects_Get_class( Objects_Id id ) @@ -76,15 +72,13 @@ RTEMS_INLINE_ROUTINE uint32_t _Objects_Get_class( ((id >> OBJECTS_CLASS_START_BIT) & OBJECTS_CLASS_VALID_BITS); } -/*PAGE - * - * _Objects_Get_node +/** + * This function returns the node portion of the ID. * - * DESCRIPTION: + * @param[in] id is the object Id to be processed * - * This function returns the node portion of the ID. + * @return This method returns the node portion of an object ID. */ - RTEMS_INLINE_ROUTINE uint32_t _Objects_Get_node( Objects_Id id ) @@ -92,15 +86,13 @@ RTEMS_INLINE_ROUTINE uint32_t _Objects_Get_node( return (id >> OBJECTS_NODE_START_BIT) & OBJECTS_NODE_VALID_BITS; } -/*PAGE - * - * _Objects_Get_index +/** + * This function returns the index portion of the ID. * - * DESCRIPTION: + * @param[in] id is the Id to be processed * - * This function returns the index portion of the ID. + * @return This method returns the class portion of the specified object ID. */ - RTEMS_INLINE_ROUTINE uint32_t _Objects_Get_index( Objects_Id id ) @@ -108,15 +100,14 @@ RTEMS_INLINE_ROUTINE uint32_t _Objects_Get_index( return (id >> OBJECTS_INDEX_START_BIT) & OBJECTS_INDEX_VALID_BITS; } -/*PAGE - * - * _Objects_Is_class_valid +/** + * This function returns TRUE if the class is valid. * - * DESCRIPTION: + * @param[in] the_class is the class portion of an object ID. * - * This function returns TRUE if the class is valid. + * @return This method returns TRUE if the specified class value is valid + * and FALSE otherwise. */ - RTEMS_INLINE_ROUTINE boolean _Objects_Is_class_valid( uint32_t the_class ) @@ -125,17 +116,17 @@ RTEMS_INLINE_ROUTINE boolean _Objects_Is_class_valid( return TRUE; /* the_class && the_class <= OBJECTS_CLASSES_LAST; */ } -/*PAGE - * - * _Objects_Is_local_node - * - * DESCRIPTION: - * +#if defined(RTEMS_MULTIPROCESSING) +/** * This function returns TRUE if the node is of the local object, and * FALSE otherwise. + * + * @param[in] node is the node number and corresponds to the node number + * portion of an object ID. + * + * @return This method returns TRUE if the specified node is the local node + * and FALSE otherwise. */ - -#if defined(RTEMS_MULTIPROCESSING) RTEMS_INLINE_ROUTINE boolean _Objects_Is_local_node( uint32_t node ) @@ -144,16 +135,17 @@ RTEMS_INLINE_ROUTINE boolean _Objects_Is_local_node( } #endif -/*PAGE +/** + * This function returns TRUE if the id is of a local object, and + * FALSE otherwise. * - * _Objects_Is_local_id + * @param[in] id is an object ID * - * DESCRIPTION: + * @return This method returns TRUE if the specified object Id is local + * and FALSE otherwise. * - * This function returns TRUE if the id is of a local object, and - * FALSE otherwise. + * @note On a single processor configuration, this always returns TRUE. */ - RTEMS_INLINE_ROUTINE boolean _Objects_Is_local_id( Objects_Id id ) @@ -165,17 +157,16 @@ RTEMS_INLINE_ROUTINE boolean _Objects_Is_local_id( #endif } - -/*PAGE - * - * _Objects_Are_ids_equal - * - * DESCRIPTION: - * +/** * This function returns TRUE if left and right are equal, * and FALSE otherwise. + * + * @param[in] left is the Id on the left hand side of the comparison + * @param[in] right is the Id on the right hand side of the comparison + * + * @return This method returns TRUE if the specified object IDs are equal + * and FALSE otherwise. */ - RTEMS_INLINE_ROUTINE boolean _Objects_Are_ids_equal( Objects_Id left, Objects_Id right @@ -184,16 +175,16 @@ RTEMS_INLINE_ROUTINE boolean _Objects_Are_ids_equal( return ( left == right ); } -/*PAGE - * - * _Objects_Get_local_object - * - * DESCRIPTION: - * +/** * This function returns a pointer to the local_table object * referenced by the index. + * + * @param[in] information points to an Object Information Table + * @param[in] index is the index of the object the caller wants to access + * + * @return This method returns a pointer to a local object or NULL if the + * index is invalid. */ - RTEMS_INLINE_ROUTINE Objects_Control *_Objects_Get_local_object( Objects_Information *information, uint16_t index @@ -204,14 +195,13 @@ RTEMS_INLINE_ROUTINE Objects_Control *_Objects_Get_local_object( return information->local_table[ index ]; } -/*PAGE - * - * _Objects_Set_local_object - * - * DESCRIPTION: - * +/** * This function sets the pointer to the local_table object * referenced by the index. + * + * @param[in] information points to an Object Information Table + * @param[in] index is the index of the object the caller wants to access + * @param[in] the_object is the local object pointer */ RTEMS_INLINE_ROUTINE void _Objects_Set_local_object( @@ -224,17 +214,16 @@ RTEMS_INLINE_ROUTINE void _Objects_Set_local_object( information->local_table[ index ] = the_object; } - -/*PAGE +/** + * This function return the information structure given + * an id of an object. * - * _Objects_Get_information + * @param[in] id is an object ID * - * DESCRIPTION: * - * This function return the information structure given - * an id of an object. + * @return This method returns a pointer to the Object Information Table + * for the class of objects which corresponds to this object ID. */ - RTEMS_INLINE_ROUTINE Objects_Information *_Objects_Get_information( Objects_Id id ) @@ -252,16 +241,14 @@ RTEMS_INLINE_ROUTINE Objects_Information *_Objects_Get_information( return _Objects_Information_table[ the_api ][ the_class ]; } -/*PAGE - * - * _Objects_Open - * - * DESCRIPTION: - * +/** * This function places the_object control pointer and object name * in the Local Pointer and Local Name Tables, respectively. + * + * @param[in] information points to an Object Information Table + * @param[in] the_object is a pointer to an object + * @param[in] name is the name of the object to make accessible */ - RTEMS_INLINE_ROUTINE void _Objects_Open( Objects_Information *information, Objects_Control *the_object, @@ -281,16 +268,13 @@ RTEMS_INLINE_ROUTINE void _Objects_Open( the_object->name = name; } -/*PAGE - * - * _Objects_Close - * - * DESCRIPTION: - * +/** * This function removes the_object control pointer and object name * in the Local Pointer and Local Name Tables. + * + * @param[in] information points to an Object Information Table + * @param[in] the_object is a pointer to an object */ - RTEMS_INLINE_ROUTINE void _Objects_Close( Objects_Information *information, Objects_Control *the_object @@ -304,15 +288,12 @@ RTEMS_INLINE_ROUTINE void _Objects_Close( the_object->name = 0; } -/*PAGE - * - * _Objects_Namespace_remove - * - * DESCRIPTION: - * +/** * This function removes the_object from the namespace. + * + * @param[in] information points to an Object Information Table + * @param[in] the_object is a pointer to an object */ - RTEMS_INLINE_ROUTINE void _Objects_Namespace_remove( Objects_Information *information, Objects_Control *the_object -- cgit v1.2.3