Index: cpukit/include/rtems/score/objectimpl.h
===================================================================
--- cpukit/include/rtems/score/objectimpl.h	(revision ae8be3f1c2f19030e7e83dcf7d3f3db586fdc128)
+++ cpukit/include/rtems/score/objectimpl.h	(revision c389f5b713f94c52e4aef2ce3b92480b359ae4db)
@@ -1,4 +1,6 @@
 /**
  * @file
+ *
+ * @ingroup RTEMSScoreObject
  *
  * @brief Inlined Routines in the Object Handler
@@ -94,7 +96,7 @@
 
 /**
- *  This function extends an object class information record.
- *
- *  @param[in] information points to an object class information block.
+ * @brief Extends an object class information record.
+ *
+ * @param information Points to an object class information block.
  */
 void _Objects_Extend_information(
@@ -103,12 +105,12 @@
 
 /**
- *  @brief Shrink an object class information record
- *
- *  This function shrink an object class information record.
- *  The object's name and object space are released. The local_table
- *  etc block does not shrink. The InActive list needs to be scanned
- *  to find the objects are remove them.
- *
- *  @param[in] information points to an object class information block.
+ * @brief Shrinks an object class information record.
+ *
+ * This function shrinks an object class information record.
+ * The object's name and object space are released. The local_table
+ * etc block does not shrink. The InActive list needs to be scanned
+ * to find the objects are remove them.
+ *
+ * @param information Points to an object class information block.
  */
 void _Objects_Shrink_information(
@@ -121,16 +123,19 @@
  * The objects information must be statically pre-initialized with the
  * OBJECTS_INFORMATION_DEFINE() macro before this function is called.
+ *
+ * @param information The object information to be initialized.
  */
 void _Objects_Initialize_information( Objects_Information *information );
 
 /**
- *  @brief Object API Maximum Class
- *
- *  This function returns the highest numeric value of a valid
- *  API for the specified @a api.
- *
- *  @param[in] api is the API of interest
- *
- *  @retval A positive integer on success and 0 otherwise.
+ * @brief Returns highest numeric value of a valid API for the specified API.
+ *
+ * This function returns the highest numeric value of a valid
+ * API for the specified @a api.
+ *
+ * @param api The API of interest.
+ *
+ * @retval some_value Positive integer on success.
+ * @retval 0 The method failed.
  */
 unsigned int _Objects_API_maximum_class(
@@ -146,8 +151,8 @@
  *   initialization.
  *
- * @param[in] information The object information block.
- *
+ * @param[in, out] information The object information block.
+ *
+ * @retval object The allocated object.
  * @retval NULL No object available.
- * @retval object The allocated object.
  *
  * @see _Objects_Allocate() and _Objects_Free().
@@ -189,8 +194,8 @@
  * @endcode
  *
- * @param[in] information The object information block.
- *
+ * @param[in, out] information The object information block.
+ *
+ * @retval object The allocated object.
  * @retval NULL No object available.
- * @retval object The allocated object.
  *
  * @see _Objects_Free().
@@ -203,6 +208,6 @@
  * Appends the object to the chain of inactive objects.
  *
- * @param[in] information The object information block.
- * @param[in] the_object The object to free.
+ * @param information The object information block.
+ * @param[out] the_object The object to free.
  *
  * @see _Objects_Allocate().
@@ -278,18 +283,18 @@
 
 /**
- *  @brief Converts an object name to an Id.
- *
- *  This method converts an object name to an Id.  It performs a look up
- *  using the object information block for this object class.
- *
- *  @param[in] information points to an object class information block.
- *  @param[in] name is the name of the object to find.
- *  @param[in] node is the set of nodes to search.
- *  @param[in] id will contain the Id if the search is successful.
- *
- *  @retval This method returns one of the values from the
- *          @ref Objects_Name_or_id_lookup_errors enumeration to indicate
- *          successful or failure.  On success @a id will contain the Id of
- *          the requested object.
+ * @brief Converts an object name to an Id.
+ *
+ * This method converts an object name to an Id.  It performs a look up
+ * using the object information block for this object class.
+ *
+ * @param information points to an object class information block.
+ * @param name is the name of the object to find.
+ * @param node is the set of nodes to search.
+ * @param[out] id will contain the Id if the search is successful.
+ *
+ * @retval OBJECTS_NAME_OR_ID_LOOKUP_SUCCESSFUL The operations was successful
+ *      @a id contains the ID.
+ * @retval OBJECTS_INVALID_NAME The name was invalid.
+ * @retval OBJECTS_INVALID_ID The id is not 0 before the operation.
  */
 Objects_Name_or_id_lookup_errors _Objects_Name_to_id_u32(
@@ -313,10 +318,10 @@
  * @param information The object information.  Must not be NULL.
  * @param name The object name.
- * @param name_length_p Optional parameter to return the name length.
- * @param error The error indication in case of failure.  Must not be NULL.
- *
+ * @param[out] name_length_p Optional parameter to return the name length.
+ * @param[out] error The error indication in case of failure.  Must not be NULL.
+ *
+ * @retval pointer The first object according to object index associated with
+ *      this name.
  * @retval NULL No object exists for this name or invalid parameters.
- * @retval other The first object according to object index associated with
- * this name.
  */
 Objects_Control *_Objects_Get_by_name(
@@ -328,19 +333,18 @@
 
 /**
- *  @brief Implements the common portion of the object Id to name directives.
- *
- *  This function implements the common portion of the object Id
- *  to name directives.  This function returns the name
- *  associated with object id.
- *
- *  @param[in] id is the Id of the object whose name we are locating.
- *  @param[in] name will contain the name of the object, if found.
- *
- *  @retval This method returns one of the values from the
- *          @ref Objects_Name_or_id_lookup_errors enumeration to indicate
- *          successful or failure.  On success @a name will contain the name of
- *          the requested object.
- *
- *  @note This function currently does not support string names.
+ * @brief Returns the name associated with object id.
+ *
+ * This function implements the common portion of the object Id
+ * to name directives.  This function returns the name
+ * associated with object id.
+ *
+ * @param id is the Id of the object whose name we are locating.
+ * @param[out] name will contain the name of the object, if found.
+ *
+ * @retval OBJECTS_NAME_OR_ID_LOOKUP_SUCCESSFUL The operation succeeded.  @a name
+ *      contains the name of the object.
+ * @retval OBJECTS_INVALID_ID The id is invalid, the operation failed.
+ *
+ * @note This function currently does not support string names.
  */
 Objects_Name_or_id_lookup_errors _Objects_Id_to_name (
@@ -358,14 +362,14 @@
  *
  * @param id The object identifier.  This is the first parameter since usual
- *   callers get the object identifier as the first parameter themself.
+ *      callers get the object identifier as the first parameter themself.
  * @param lock_context The interrupt lock context.  This is the second
- *   parameter since usual callers get the interrupt lock context as the second
- *   parameter themself.
+ *      parameter since usual callers get the interrupt lock context as the second
+ *      parameter themself.
  * @param information The object class information block.
  *
+ * @retval pointer The pointer to the associated object control block.
+ *      Interrupts are now disabled and must be restored using the specified lock
+ *      context via _ISR_lock_ISR_enable() or _ISR_lock_Release_and_ISR_enable().
  * @retval NULL No associated object exists.
- * @retval other The pointer to the associated object control block.
- * Interrupts are now disabled and must be restored using the specified lock
- * context via _ISR_lock_ISR_enable() or _ISR_lock_Release_and_ISR_enable().
  */
 Objects_Control *_Objects_Get(
@@ -376,24 +380,22 @@
 
 /**
- *  @brief  Maps object ids to object control blocks.
- *
- *  This function maps object ids to object control blocks.
- *  If id corresponds to a local object, then it returns
- *  the_object control pointer which maps to id and location
- *  is set to OBJECTS_LOCAL.  If the object class supports global
- *  objects and the object id is global and resides on a remote
- *  node, then location is set to OBJECTS_REMOTE, and the_object
- *  is undefined.  Otherwise, location is set to OBJECTS_ERROR
- *  and the_object is undefined.
- *
- *  @param[in] id is the Id of the object whose name we are locating.
- *    This is the first parameter since usual callers get the object identifier
- *    as the first parameter themself.
- *  @param[in] information points to an object class information block.
- *
- *  @retval This method returns one of the values from the
- *          @ref Objects_Name_or_id_lookup_errors enumeration to indicate
- *          successful or failure.  On success @a id will contain the Id of
- *          the requested object.
+ * @brief  Maps object ids to object control blocks.
+ *
+ * This function maps object ids to object control blocks.
+ * If id corresponds to a local object, then it returns
+ * the_object control pointer which maps to id and location
+ * is set to OBJECTS_LOCAL.  If the object class supports global
+ * objects and the object id is global and resides on a remote
+ * node, then location is set to OBJECTS_REMOTE, and the_object
+ * is undefined.  Otherwise, location is set to OBJECTS_ERROR
+ * and the_object is undefined.
+ *
+ * @param id The Id of the object whose name we are locating.
+ *   This is the first parameter since usual callers get the object identifier
+ *   as the first parameter themself.
+ * @param information Points to an object class information block.
+ *
+ * @retval pointer The local object corresponding to the given id.
+ * @retval NULL The object to the given id was not found locally.
  */
 Objects_Control *_Objects_Get_no_protection(
@@ -403,16 +405,16 @@
 
 /**
- *  Gets the next open object after the specified object identifier.
- *
- *  Locks the object allocator mutex in case a next object exists.
- *
- *  @param[in] id is the Id of the object whose name we are locating.
- *    This is the first parameter since usual callers get the object identifier
- *    as the first parameter themself.
- *  @param[in] information points to an object class information block.
- *  @param[in] next_id_p is the Id of the next object we will look at.
- *
- *  @retval This method returns the pointer to the object located or
- *          NULL on error.
+ * @brief Gets the next open object after the specified object identifier.
+ *
+ * Locks the object allocator mutex in case a next object exists.
+ *
+ * @param id The Id of the object whose name we are locating.
+ *   This is the first parameter since usual callers get the object identifier
+ *   as the first parameter themself.
+ * @param information Points to an object class information block.
+ * @param[in, out] next_id_p The Id of the next object we will look at.
+ *
+ * @retval pointer Pointer to the located object.
+ * @retval NULL An error occured.
  */
 Objects_Control *_Objects_Get_next(
@@ -423,15 +425,16 @@
 
 /**
- *  @brief Get object information.
- *
- *  This function return the information structure given
- *  an the API and Class.  This can be done independent of
- *  the existence of any objects created by the API.
- *
- *  @param[in] the_api indicates the API for the information we want
- *  @param[in] the_class indicates the Class for the information we want
- *
- *  @retval This method returns a pointer to the Object Information Table
- *          for the class of objects which corresponds to this object ID.
+ * @brief Gets object information.
+ *
+ * This function returns the information structure given
+ * an API and Class.  This can be done independent of the
+ * existence of any objects created by the API.
+ *
+ * @param the_api Indicates the API for the information we want
+ * @param the_class Indicates the Class for the information we want
+ *
+ * @retval pointer Pointer to the Object Information Table
+ *         for the class of objects which corresponds to this object ID.
+ * @retval NULL An error occured.
  */
 Objects_Information *_Objects_Get_information(
@@ -441,13 +444,14 @@
 
 /**
- *  @brief Get information of an object from an ID.
- *
- *  This function return the information structure given
- *  an @a id of an object.
- *
- *  @param[in] id is the object ID to get the information from
- *
- *  @retval This method returns a pointer to the Object Information Table
- *          for the class of objects which corresponds to this object ID.
+ * @brief Gets information of an object from an ID.
+ *
+ * This function returns the information structure given
+ * an @a id of an object.
+ *
+ * @param id The object ID to get the information from.
+ *
+ * @retval pointer Pointer to the Object Information Table
+ *         for the class of objects which corresponds to this object ID.
+ * @retval NULL An error occured.
  */
 Objects_Information *_Objects_Get_information_id(
@@ -456,16 +460,16 @@
 
 /**
- *  @brief Gets object name in the form of a C string.
- *
- *  This method objects the name of an object and returns its name
- *  in the form of a C string.  It attempts to be careful about
- *  overflowing the user's string and about returning unprintable characters.
- *
- *  @param[in] id is the object to obtain the name of
- *  @param[in] length indicates the length of the caller's buffer
- *  @param[in] name points a string which will be filled in.
- *
- *  @retval This method returns @a name or NULL on error. @a *name will
- *          contain the name if successful.
+ * @brief Gets object name in the form of a C string.
+ *
+ * This method gets the name of an object and returns its name
+ * in the form of a C string.  It attempts to be careful about
+ * overflowing the user's string and about returning unprintable characters.
+ *
+ * @param id The object to obtain the name of.
+ * @param length Indicates the length of the caller's buffer.
+ * @param[out] name A string which will be filled in.
+ *
+ * @retval @a name The operation was succeeded and the string was correctly filled in.
+ * @retval NULL An error occured.
  */
 char *_Objects_Get_name_as_string(
@@ -480,11 +484,11 @@
  * Non-printable characters according to isprint() are converted to '*'.
  *
- * @param[in] name The object name.
- * @param[in] is_string Indicates if the object name is a string or a four
+ * @param name The object name.
+ * @param is_string Indicates if the object name is a string or a four
  *   character array (32-bit unsigned integer).
- * @param[in] buffer The string buffer for the text representation.
- * @param[in] buffer_size The buffer size in characters.
- *
- * @retval The length of the text representation.  May be greater than or equal
+ * @param[out] buffer The string buffer for the text representation.
+ * @param buffer_size The buffer size in characters.
+ *
+ * @return The length of the text representation.  May be greater than or equal
  * to the buffer size if truncation occurred.
  */
@@ -497,15 +501,16 @@
 
 /**
- *  @brief Set objects name.
- *
- *  This method sets the object name to either a copy of a string
- *  or up to the first four characters of the string based upon
- *  whether this object class uses strings for names.
- *
- *  @param[in] information points to the object information structure
- *  @param[in] the_object is the object to operate upon
- *  @param[in] name is a pointer to the name to use
- *
- *  @retval If successful, true is returned.  Otherwise false is returned.
+ * @brief Sets objects name.
+ *
+ * This method sets the object name to either a copy of a string
+ * or up to the first four characters of the string based upon
+ * whether this object class uses strings for names.
+ *
+ * @param information points to the object information structure
+ * @param[out] the_object is the object to operate upon
+ * @param name is a pointer to the name to use
+ *
+ * @retval true The operation succeeded.
+ * @retval false The operation failed.
  */
 bool _Objects_Set_name(
@@ -518,6 +523,6 @@
  * @brief Removes object with a 32-bit integer name from its namespace.
  *
- * @param[in] information The corresponding object information table.
- * @param[in] the_object The object.
+ * @param information The corresponding object information table.
+ * @param[out] the_object The object to operate upon.
  */
 void _Objects_Namespace_remove_u32(
@@ -529,6 +534,6 @@
  * @brief Removes object with a string name from its namespace.
  *
- * @param[in] information The corresponding object information table.
- * @param[in] the_object The object.
+ * @param information The corresponding object information table.
+ * @param[out] the_object The object the object to operate upon.
  */
 void _Objects_Namespace_remove_string(
@@ -538,11 +543,11 @@
 
 /**
- *  @brief Close object.
- *
- *  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
+ * @brief Closes object.
+ *
+ * This function removes the_object control pointer and object name
+ * in the Local Pointer and Local Name Tables.
+ *
+ * @param information Points to an Object Information Table.
+ * @param[out] the_object A pointer to an object.
  */
 void _Objects_Close(
@@ -554,7 +559,7 @@
  * @brief Returns the count of active objects.
  *
- * @param[in] information The object information table.
- *
- * @retval The count of active objects.
+ * @param information The object information table.
+ *
+ * @return The count of active objects.
  */
 Objects_Maximum _Objects_Active_count(
@@ -562,4 +567,12 @@
 );
 
+/**
+ * @brief Returns if the object has a string name.
+ *
+ * @param information The object information table.
+ *
+ * @retval true The object has a string name.
+ * @retval false The object does not have a string name.
+ */
 RTEMS_INLINE_ROUTINE bool _Objects_Has_string_name(
   const Objects_Information *information
@@ -569,4 +582,11 @@
 }
 
+/**
+ * @brief Returns the object's objects per block.
+ *
+ * @param information The object information table.
+ *
+ * @return The number of objects per block of @a information.
+ */
 RTEMS_INLINE_ROUTINE Objects_Maximum _Objects_Extend_size(
   const Objects_Information *information
@@ -577,10 +597,10 @@
 
 /**
- * This function returns true if the api is valid.
- *
- * @param[in] the_api is the api portion of an object ID.
- *
- * @return This method returns true if the specified api value is valid
- *         and false otherwise.
+ * @brief Checks if the api is valid.
+ *
+ * @param the_api is the api portion of an object ID.
+ *
+ * @retval true The specified api value is valid.
+ * @retval false The specified api value is not valid.
  */
 RTEMS_INLINE_ROUTINE bool _Objects_Is_api_valid(
@@ -594,12 +614,11 @@
 
 /**
- * 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
+ * @brief Checks if the node is of the local object.
+ *
+ * @param node 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.
+ * @retval true The specified node is the local node.
+ * @retval false The specified node is not the local node.
  */
 RTEMS_INLINE_ROUTINE bool _Objects_Is_local_node(
@@ -611,11 +630,10 @@
 
 /**
- * This function returns true if the id is of a local object, and
- * false otherwise.
- *
- * @param[in] id is an object ID
- *
- * @return This method returns true if the specified object Id is local
- *         and false otherwise.
+ * @brief Checks if the id is of a local object.
+ *
+ * @param id The object ID.
+ *
+ * @retval true The specified object Id is local.
+ * @retval false The specified object Id is not local.
  *
  * @note On a single processor configuration, this always returns true.
@@ -637,12 +655,11 @@
 
 /**
- * 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.
+ * @brief Checks if two object IDs are equal.
+ *
+ * @param left The Id on the left hand side of the comparison.
+ * @param right The Id on the right hand side of the comparison.
+ *
+ * @retval true The specified object IDs are equal.
+ * @retval false The specified object IDs are not equal.
  */
 RTEMS_INLINE_ROUTINE bool _Objects_Are_ids_equal(
@@ -655,9 +672,9 @@
 
 /**
- * Returns the identifier with the minimum index for the specified identifier.
+ * @brief Returns the identifier with the minimum index for the specified identifier.
  *
  * The specified identifier must have valid API, class and node fields.
  *
- * @param[in] id The identifier to be processed.
+ * @param id The identifier to be processed.
  *
  * @return The corresponding ID with the minimum index.
@@ -671,7 +688,7 @@
 
 /**
- * Returns the maximum index of the specified object class.
- *
- * @param[in] information The object information.
+ * @brief Returns the maximum index of the specified object class.
+ *
+ * @param information The object information.
  *
  * @return The maximum index of the specified object class.
@@ -685,11 +702,11 @@
 
 /**
- * @brief Returns true if the automatic object extension (unlimited objects) is
- * enabled, otherwise false.
- *
- * @param[in] information The object information.
+ * @brief Checks if the automatic object extension (unlimited objects) is
+ * enabled.
+ *
+ * @param information The object information.
  *
  * @retval true The automatic object extension (unlimited objects) is enabled.
- * @retval false Otherwise.
+ * @retval false The automatic object extension (unlimited objects) is not enabled.
  */
 RTEMS_INLINE_ROUTINE Objects_Maximum _Objects_Is_auto_extend(
@@ -701,10 +718,10 @@
 
 /**
- * This function sets the pointer to the local_table object
+ * @brief 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
+ * @param[in, out] information Points to an Object Information Table.
+ * @param index The index of the object the caller wants to access.
+ * @param the_object The local object pointer.
  *
  * @note This routine is ONLY to be called in places where the
@@ -732,10 +749,12 @@
 
 /**
+ * @brief Invalidates an object Id.
+ *
  * This function sets the pointer to the local_table object
- * referenced by the index to a NULL so the object Id is invalid
+ * referenced by the index to NULL so the object Id is invalid
  * after this call.
  *
- * @param[in] information points to an Object Information Table
- * @param[in] the_object is the local object pointer
+ * @param[in, out] information points to an Object Information Table.
+ * @param the_object The local object pointer.
  *
  * @note This routine is ONLY to be called in places where the
@@ -761,10 +780,12 @@
 
 /**
- * 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
+ * @brief Places the_object control pointer and object name
+ *      in the Local Pointer and Local Name Tables, respectively.
+ *
+ * This method uses Objects_Name for the object name.
+ *
+ * @param[in, out] information Points to an Object Information Table.
+ * @param the_object Pointer to an object.
+ * @param name The name of the object to make accessible.
  */
 RTEMS_INLINE_ROUTINE void _Objects_Open(
@@ -787,10 +808,12 @@
 
 /**
- * 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
+ * @brief Places the_object control pointer and object name
+ *      in the Local Pointer and Local Name Tables, respectively.
+ *
+ * This method uses uint32_t for the object name.
+ *
+ * @param[in, out] information Points to an Object Information Table.
+ * @param the_object Pointer to an object.
+ * @param name The name of the object to make accessible.
  */
 RTEMS_INLINE_ROUTINE void _Objects_Open_u32(
@@ -811,10 +834,12 @@
 
 /**
- * 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
+ * @brief Places the_object control pointer and object name
+ *      in the Local Pointer and Local Name Tables, respectively.
+ *
+ * This method uses a String for the object name.
+ *
+ * @param[in, out] information Points to an Object Information Table.
+ * @param the_object Pointer to an object.
+ * @param name The name of the object to make accessible.
  */
 RTEMS_INLINE_ROUTINE void _Objects_Open_string(
@@ -865,4 +890,10 @@
 }
 
+/**
+ * @brief Checks if the allocator is the owner of the object allocator mutex
+ *
+ * @retval true The allocator is the owner of the object allocator mutex.
+ * @retval false The allocato is not the owner of the object allocator mutex.
+ */
 RTEMS_INLINE_ROUTINE bool _Objects_Allocator_is_owner( void )
 {
