rtems: Document object name to id directives

9 files changed, 299 insertions, 30 deletions

diff --git a/cpukit/include/rtems/extension.h b/cpukit/include/rtems/extension.h
index 870fa5b215..44264c4176 100644
--- a/cpukit/include/rtems/extension.h
+++ b/cpukit/include/rtems/extension.h
@@ -122,11 +122,34 @@ typedef Internal_errors_Source rtems_fatal_source;
 /**
  * @ingroup RTEMSAPIClassicUserext
  *
- * @brief %
+ * @brief Identifies an extension set object by the specified object name.
  *
- * @param name %
+ * This directive obtains the extension set identifier associated with the
+ * extension set name specified in ``name``.
  *
- * @param id %
+ * If the extension set name is not unique, then the extension set identifier
+ * will match the first extension set with that name in the search order.
+ * However, this extension set identifier is not guaranteed to correspond to
+ * the desired extension set.  The extension set identifier is used with other
+ * extension related directives to access the extension set.
+ *
+ * The objects are searched from lowest to the highest index.  Only the local
+ * node is searched.
+ *
+ * @param name is the object name to look up.
+ *
+ * @param[out] id is the pointer to an object identifier variable.  The object
+ *   identifier of an object with the specified name will be stored in this
+ *   variable, in case of a successful operation.
+ *
+ * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
+ *
+ * @retval ::RTEMS_INVALID_ADDRESS The id parameter was NULL.
+ *
+ * @retval ::RTEMS_INVALID_NAME The name parameter was 0.
+ *
+ * @retval ::RTEMS_INVALID_NAME There was no object with the specified name on
+ *   the local node.
  */
 rtems_status_code rtems_extension_ident( rtems_name name, rtems_id *id );
 
diff --git a/cpukit/include/rtems/rtems/barrier.h b/cpukit/include/rtems/rtems/barrier.h
index 79a349eb68..82fd22fee3 100644
--- a/cpukit/include/rtems/rtems/barrier.h
+++ b/cpukit/include/rtems/rtems/barrier.h
@@ -96,11 +96,34 @@ rtems_status_code rtems_barrier_delete( rtems_id id );
 /**
  * @ingroup RTEMSAPIClassicBarrier
  *
- * @brief %
+ * @brief Identifies a barrier object by the specified object name.
  *
- * @param name %
+ * This directive obtains the barrier identifier associated with the barrier
+ * name specified in ``name``.
  *
- * @param id %
+ * If the barrier name is not unique, then the barrier identifier will match
+ * the first barrier with that name in the search order.  However, this barrier
+ * identifier is not guaranteed to correspond to the desired barrier.  The
+ * barrier identifier is used with other barrier related directives to access
+ * the barrier.
+ *
+ * The objects are searched from lowest to the highest index.  Only the local
+ * node is searched.
+ *
+ * @param name is the object name to look up.
+ *
+ * @param[out] id is the pointer to an object identifier variable.  The object
+ *   identifier of an object with the specified name will be stored in this
+ *   variable, in case of a successful operation.
+ *
+ * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
+ *
+ * @retval ::RTEMS_INVALID_ADDRESS The id parameter was NULL.
+ *
+ * @retval ::RTEMS_INVALID_NAME The name parameter was 0.
+ *
+ * @retval ::RTEMS_INVALID_NAME There was no object with the specified name on
+ *   the local node.
  */
 rtems_status_code rtems_barrier_ident( rtems_name name, rtems_id *id );
 
diff --git a/cpukit/include/rtems/rtems/dpmem.h b/cpukit/include/rtems/rtems/dpmem.h
index b1b45e5978..d9af05ed87 100644
--- a/cpukit/include/rtems/rtems/dpmem.h
+++ b/cpukit/include/rtems/rtems/dpmem.h
@@ -116,11 +116,34 @@ rtems_status_code rtems_port_external_to_internal(
 /**
  * @ingroup RTEMSAPIClassicDPMem
  *
- * @brief %
+ * @brief Identifies a port object by the specified object name.
  *
- * @param name %
+ * This directive obtains the port identifier associated with the port name
+ * specified in ``name``.
  *
- * @param id %
+ * If the port name is not unique, then the port identifier will match the
+ * first port with that name in the search order.  However, this port
+ * identifier is not guaranteed to correspond to the desired port.  The port
+ * identifier is used with other dual-ported memory related directives to
+ * access the port.
+ *
+ * The objects are searched from lowest to the highest index.  Only the local
+ * node is searched.
+ *
+ * @param name is the object name to look up.
+ *
+ * @param[out] id is the pointer to an object identifier variable.  The object
+ *   identifier of an object with the specified name will be stored in this
+ *   variable, in case of a successful operation.
+ *
+ * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
+ *
+ * @retval ::RTEMS_INVALID_ADDRESS The id parameter was NULL.
+ *
+ * @retval ::RTEMS_INVALID_NAME The name parameter was 0.
+ *
+ * @retval ::RTEMS_INVALID_NAME There was no object with the specified name on
+ *   the local node.
  */
 rtems_status_code rtems_port_ident( rtems_name name, rtems_id *id );
 
diff --git a/cpukit/include/rtems/rtems/message.h b/cpukit/include/rtems/rtems/message.h
index 2292f2d8a4..565db9d190 100644
--- a/cpukit/include/rtems/rtems/message.h
+++ b/cpukit/include/rtems/rtems/message.h
@@ -146,13 +146,57 @@ rtems_status_code rtems_message_queue_get_number_pending(
 /**
  * @ingroup RTEMSAPIClassicMessage
  *
- * @brief %
+ * @brief Identifies a message queue object by the specified object name.
  *
- * @param name %
+ * This directive obtains the message queue identifier associated with the
+ * message queue name specified in ``name``.
  *
- * @param node %
+ * The node to search is specified in ``node``.  It shall be
  *
- * @param id %
+ * * a valid node number,
+ *
+ * * the constant #RTEMS_SEARCH_ALL_NODES to search in all nodes,
+ *
+ * * the constant #RTEMS_SEARCH_LOCAL_NODE to search in the local node only, or
+ *
+ * * the constant #RTEMS_SEARCH_OTHER_NODES to search in all nodes except the
+ *   local node.
+ *
+ * If the message queue name is not unique, then the message queue identifier
+ * will match the first message queue with that name in the search order.
+ * However, this message queue identifier is not guaranteed to correspond to
+ * the desired message queue.  The message queue identifier is used with other
+ * message related directives to access the message queue.
+ *
+ * If node is #RTEMS_SEARCH_ALL_NODES, all nodes are searched with the local
+ * node being searched first.  All other nodes are searched with the lowest
+ * numbered node searched first.
+ *
+ * If node is a valid node number which does not represent the local node, then
+ * only the message queues exported by the designated node are searched.
+ *
+ * This directive does not generate activity on remote nodes.  It accesses only
+ * the local copy of the global object table.
+ *
+ * @param name is the object name to look up.
+ *
+ * @param node is the node or node set to search for a matching object.
+ *
+ * @param[out] id is the pointer to an object identifier variable.  The object
+ *   identifier of an object with the specified name will be stored in this
+ *   variable, in case of a successful operation.
+ *
+ * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
+ *
+ * @retval ::RTEMS_INVALID_ADDRESS The id parameter was NULL.
+ *
+ * @retval ::RTEMS_INVALID_NAME The name parameter was 0.
+ *
+ * @retval ::RTEMS_INVALID_NAME There was no object with the specified name on
+ *   the specified nodes.
+ *
+ * @retval ::RTEMS_INVALID_NODE In multiprocessing configurations, the
+ *   specified node was invalid.
  */
 rtems_status_code rtems_message_queue_ident(
   rtems_name name,
diff --git a/cpukit/include/rtems/rtems/part.h b/cpukit/include/rtems/rtems/part.h
index d0c87df211..57e705c38a 100644
--- a/cpukit/include/rtems/rtems/part.h
+++ b/cpukit/include/rtems/rtems/part.h
@@ -114,13 +114,57 @@ rtems_status_code rtems_partition_get_buffer( rtems_id id, void **buffer );
 /**
  * @ingroup RTEMSAPIClassicPart
  *
- * @brief %
+ * @brief Identifies a partition object by the specified object name.
  *
- * @param name %
+ * This directive obtains the partition identifier associated with the
+ * partition name specified in ``name``.
  *
- * @param node %
+ * The node to search is specified in ``node``.  It shall be
  *
- * @param id %
+ * * a valid node number,
+ *
+ * * the constant #RTEMS_SEARCH_ALL_NODES to search in all nodes,
+ *
+ * * the constant #RTEMS_SEARCH_LOCAL_NODE to search in the local node only, or
+ *
+ * * the constant #RTEMS_SEARCH_OTHER_NODES to search in all nodes except the
+ *   local node.
+ *
+ * If the partition name is not unique, then the partition identifier will
+ * match the first partition with that name in the search order.  However, this
+ * partition identifier is not guaranteed to correspond to the desired
+ * partition.  The partition identifier is used with other partition related
+ * directives to access the partition.
+ *
+ * If node is #RTEMS_SEARCH_ALL_NODES, all nodes are searched with the local
+ * node being searched first.  All other nodes are searched with the lowest
+ * numbered node searched first.
+ *
+ * If node is a valid node number which does not represent the local node, then
+ * only the partitions exported by the designated node are searched.
+ *
+ * This directive does not generate activity on remote nodes.  It accesses only
+ * the local copy of the global object table.
+ *
+ * @param name is the object name to look up.
+ *
+ * @param node is the node or node set to search for a matching object.
+ *
+ * @param[out] id is the pointer to an object identifier variable.  The object
+ *   identifier of an object with the specified name will be stored in this
+ *   variable, in case of a successful operation.
+ *
+ * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
+ *
+ * @retval ::RTEMS_INVALID_ADDRESS The id parameter was NULL.
+ *
+ * @retval ::RTEMS_INVALID_NAME The name parameter was 0.
+ *
+ * @retval ::RTEMS_INVALID_NAME There was no object with the specified name on
+ *   the specified nodes.
+ *
+ * @retval ::RTEMS_INVALID_NODE In multiprocessing configurations, the
+ *   specified node was invalid.
  */
 rtems_status_code rtems_partition_ident(
   rtems_name name,
diff --git a/cpukit/include/rtems/rtems/ratemon.h b/cpukit/include/rtems/rtems/ratemon.h
index 1c6cca1766..1746fff113 100644
--- a/cpukit/include/rtems/rtems/ratemon.h
+++ b/cpukit/include/rtems/rtems/ratemon.h
@@ -258,11 +258,34 @@ rtems_status_code rtems_rate_monotonic_get_status(
 /**
  * @ingroup RTEMSAPIClassicRatemon
  *
- * @brief %
+ * @brief Identifies a period object by the specified object name.
  *
- * @param name %
+ * This directive obtains the period identifier associated with the period name
+ * specified in ``name``.
  *
- * @param id %
+ * If the period name is not unique, then the period identifier will match the
+ * first period with that name in the search order.  However, this period
+ * identifier is not guaranteed to correspond to the desired period.  The
+ * period identifier is used with other rate monotonic related directives to
+ * access the period.
+ *
+ * The objects are searched from lowest to the highest index.  Only the local
+ * node is searched.
+ *
+ * @param name is the object name to look up.
+ *
+ * @param[out] id is the pointer to an object identifier variable.  The object
+ *   identifier of an object with the specified name will be stored in this
+ *   variable, in case of a successful operation.
+ *
+ * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
+ *
+ * @retval ::RTEMS_INVALID_ADDRESS The id parameter was NULL.
+ *
+ * @retval ::RTEMS_INVALID_NAME The name parameter was 0.
+ *
+ * @retval ::RTEMS_INVALID_NAME There was no object with the specified name on
+ *   the local node.
  */
 rtems_status_code rtems_rate_monotonic_ident( rtems_name name, rtems_id *id );
 
diff --git a/cpukit/include/rtems/rtems/region.h b/cpukit/include/rtems/rtems/region.h
index 2a8ec081d5..6471ab0cfc 100644
--- a/cpukit/include/rtems/rtems/region.h
+++ b/cpukit/include/rtems/rtems/region.h
@@ -189,11 +189,34 @@ rtems_status_code rtems_region_get_segment_size(
 /**
  * @ingroup RTEMSAPIClassicRegion
  *
- * @brief %
+ * @brief Identifies a region object by the specified object name.
  *
- * @param name %
+ * This directive obtains the region identifier associated with the region name
+ * specified in ``name``.
  *
- * @param id %
+ * If the region name is not unique, then the region identifier will match the
+ * first region with that name in the search order.  However, this region
+ * identifier is not guaranteed to correspond to the desired region.  The
+ * region identifier is used with other region related directives to access the
+ * region.
+ *
+ * The objects are searched from lowest to the highest index.  Only the local
+ * node is searched.
+ *
+ * @param name is the object name to look up.
+ *
+ * @param[out] id is the pointer to an object identifier variable.  The object
+ *   identifier of an object with the specified name will be stored in this
+ *   variable, in case of a successful operation.
+ *
+ * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
+ *
+ * @retval ::RTEMS_INVALID_ADDRESS The id parameter was NULL.
+ *
+ * @retval ::RTEMS_INVALID_NAME The name parameter was 0.
+ *
+ * @retval ::RTEMS_INVALID_NAME There was no object with the specified name on
+ *   the local node.
  */
 rtems_status_code rtems_region_ident( rtems_name name, rtems_id *id );
 
diff --git a/cpukit/include/rtems/rtems/sem.h b/cpukit/include/rtems/rtems/sem.h
index 6f3e8af99c..5b12e9a152 100644
--- a/cpukit/include/rtems/rtems/sem.h
+++ b/cpukit/include/rtems/rtems/sem.h
@@ -236,13 +236,57 @@ rtems_status_code rtems_semaphore_flush( rtems_id id );
 /**
  * @ingroup RTEMSAPIClassicSem
  *
- * @brief %
+ * @brief Identifies a semaphore object by the specified object name.
  *
- * @param name %
+ * This directive obtains the semaphore identifier associated with the
+ * semaphore name specified in ``name``.
  *
- * @param node %
+ * The node to search is specified in ``node``.  It shall be
  *
- * @param id %
+ * * a valid node number,
+ *
+ * * the constant #RTEMS_SEARCH_ALL_NODES to search in all nodes,
+ *
+ * * the constant #RTEMS_SEARCH_LOCAL_NODE to search in the local node only, or
+ *
+ * * the constant #RTEMS_SEARCH_OTHER_NODES to search in all nodes except the
+ *   local node.
+ *
+ * If the semaphore name is not unique, then the semaphore identifier will
+ * match the first semaphore with that name in the search order.  However, this
+ * semaphore identifier is not guaranteed to correspond to the desired
+ * semaphore.  The semaphore identifier is used with other semaphore related
+ * directives to access the semaphore.
+ *
+ * If node is #RTEMS_SEARCH_ALL_NODES, all nodes are searched with the local
+ * node being searched first.  All other nodes are searched with the lowest
+ * numbered node searched first.
+ *
+ * If node is a valid node number which does not represent the local node, then
+ * only the semaphores exported by the designated node are searched.
+ *
+ * This directive does not generate activity on remote nodes.  It accesses only
+ * the local copy of the global object table.
+ *
+ * @param name is the object name to look up.
+ *
+ * @param node is the node or node set to search for a matching object.
+ *
+ * @param[out] id is the pointer to an object identifier variable.  The object
+ *   identifier of an object with the specified name will be stored in this
+ *   variable, in case of a successful operation.
+ *
+ * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
+ *
+ * @retval ::RTEMS_INVALID_ADDRESS The id parameter was NULL.
+ *
+ * @retval ::RTEMS_INVALID_NAME The name parameter was 0.
+ *
+ * @retval ::RTEMS_INVALID_NAME There was no object with the specified name on
+ *   the specified nodes.
+ *
+ * @retval ::RTEMS_INVALID_NODE In multiprocessing configurations, the
+ *   specified node was invalid.
  */
 rtems_status_code rtems_semaphore_ident(
   rtems_name name,
diff --git a/cpukit/include/rtems/rtems/timer.h b/cpukit/include/rtems/rtems/timer.h
index 00d1307bb5..20dc312f07 100644
--- a/cpukit/include/rtems/rtems/timer.h
+++ b/cpukit/include/rtems/rtems/timer.h
@@ -257,11 +257,33 @@ rtems_status_code rtems_timer_get_information(
 /**
  * @ingroup RTEMSAPIClassicTimer
  *
- * @brief %
+ * @brief Identifies a timer object by the specified object name.
  *
- * @param name %
+ * This directive obtains the timer identifier associated with the timer name
+ * specified in ``name``.
  *
- * @param id %
+ * If the timer name is not unique, then the timer identifier will match the
+ * first timer with that name in the search order.  However, this timer
+ * identifier is not guaranteed to correspond to the desired timer.  The timer
+ * identifier is used with other timer related directives to access the timer.
+ *
+ * The objects are searched from lowest to the highest index.  Only the local
+ * node is searched.
+ *
+ * @param name is the object name to look up.
+ *
+ * @param[out] id is the pointer to an object identifier variable.  The object
+ *   identifier of an object with the specified name will be stored in this
+ *   variable, in case of a successful operation.
+ *
+ * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
+ *
+ * @retval ::RTEMS_INVALID_ADDRESS The id parameter was NULL.
+ *
+ * @retval ::RTEMS_INVALID_NAME The name parameter was 0.
+ *
+ * @retval ::RTEMS_INVALID_NAME There was no object with the specified name on
+ *   the local node.
  */
 rtems_status_code rtems_timer_ident( rtems_name name, rtems_id *id );