cpukit: Clean up Doxygen #3 (GCI 2012)

12 files changed, 76 insertions, 26 deletions

diff --git a/cpukit/rtems/include/rtems/rtems/clock.h b/cpukit/rtems/include/rtems/rtems/clock.h
index 7c12cce708..c841d1a4f8 100644
--- a/cpukit/rtems/include/rtems/rtems/clock.h
+++ b/cpukit/rtems/include/rtems/rtems/clock.h
@@ -191,7 +191,8 @@ rtems_status_code rtems_clock_set(
  *  @return This directive always returns RTEMS_SUCCESSFUL.
  *
  *  @note This method is typically called from an ISR and is the basis
- *        for all timeouts and delays.
+ *        for all timeouts and delays. This routine only works for leap-years
+ *	  through 2099.
  */
 rtems_status_code rtems_clock_tick( void );
 
@@ -256,7 +257,7 @@ bool _TOD_Validate(
 );
 
 /**
- *  @brief _TOD_To_seconds
+ *  @brief TOD to Seconds
  *
  *  This function returns the number seconds between the epoch and @a the_tod.
  *
diff --git a/cpukit/rtems/include/rtems/rtems/dpmem.h b/cpukit/rtems/include/rtems/rtems/dpmem.h
index 7ccb2255f6..4869dee6c0 100644
--- a/cpukit/rtems/include/rtems/rtems/dpmem.h
+++ b/cpukit/rtems/include/rtems/rtems/dpmem.h
@@ -101,11 +101,16 @@ rtems_status_code rtems_port_create(
 );
 
 /**
- *  @brief rtems_port_ident
+ *  @brief RTEMS Port Name to Id
  *
  *  This routine implements the rtems_port_ident directive.  This directive
  *  returns the port ID associated with name.  If more than one port is
  *  named name, then the port to which the ID belongs is arbitrary.
+ * 
+ *  @param[in] name is the user defined port name
+ *  @param[out] id is the pointer to port id
+ * 
+ *  @return RTEMS_SUCCESSFUL if successful or error code if unsuccessful
  */
 rtems_status_code rtems_port_ident(
   rtems_name    name,
@@ -123,11 +128,19 @@ rtems_status_code rtems_port_delete(
 );
 
 /**
- *  @brief rtems_port_external_to_internal
+ *  @brief RTEMS Port External to Internal
  *
  *  This routine implements the rtems_port_external_to_internal directive.
  *  It returns the internal port address which maps to the provided
- *  external port address for the specified port ID.
+ *  external port address for the specified port ID.If the given external
+ *  address is an invalid dual-ported address, then the internal address is 
+ *  set to the given external address.
+ * 
+ *  @param[in] id is the id of dp memory object
+ *  @param[in] external is the external address
+ *  @param[out] internal is the pointer of internal address to set
+ * 
+ *  @return RTEMS_SUCCESSFUL
  */
 rtems_status_code rtems_port_external_to_internal(
   rtems_id     id,
diff --git a/cpukit/rtems/include/rtems/rtems/eventmp.h b/cpukit/rtems/include/rtems/rtems/eventmp.h
index aa09e348cc..a54f79cffe 100644
--- a/cpukit/rtems/include/rtems/rtems/eventmp.h
+++ b/cpukit/rtems/include/rtems/rtems/eventmp.h
@@ -65,7 +65,7 @@ typedef struct {
  */
 
 /**
- *  @brief Event_MP_Send_request_packet
+ *  @brief Event MP Send Packet Request
  *
  *  This routine performs a remote procedure call so that a
  *  directive operation can be initiated on another node.
@@ -77,7 +77,7 @@ rtems_status_code _Event_MP_Send_request_packet (
 );
 
 /**
- *  @brief Event_MP_Send_response_packet
+ *  @brief Event MP Send Packet Response
  *
  *  This routine performs a remote procedure call so that a
  *  directive can be performed on another node.
@@ -88,7 +88,7 @@ void _Event_MP_Send_response_packet (
 );
 
 /**
- *  @brief Event_MP_Process_packet
+ *  @brief Event MP Packet Process
  *
  *  This routine performs the actions specific to this package for
  *  the request from another node.
@@ -120,7 +120,7 @@ void _Event_MP_Process_packet (
  */
 
 /**
- *  @brief Event_MP_Get_packet
+ *  @brief Event MP Get Packet
  *
  *  This function is used to obtain a event mp packet.
  */
diff --git a/cpukit/rtems/include/rtems/rtems/message.h b/cpukit/rtems/include/rtems/rtems/message.h
index 69eab62d7c..fa80862fb3 100644
--- a/cpukit/rtems/include/rtems/rtems/message.h
+++ b/cpukit/rtems/include/rtems/rtems/message.h
@@ -286,10 +286,12 @@ rtems_status_code _Message_queue_Submit(
 );
 
 /**
- *  @brief Message_queue_Allocate
+ *  @brief Message Queue Allocate
  *
  *  This function allocates a message queue control block from
  *  the inactive chain of free message queue control blocks.
+ * 
+ *  @return the_message_queue filled in if successful, NULL otherwise
  */
 Message_queue_Control *_Message_queue_Allocate (void);
 
diff --git a/cpukit/rtems/include/rtems/rtems/mp.h b/cpukit/rtems/include/rtems/rtems/mp.h
index c04b0b1c64..f7b5f20c62 100644
--- a/cpukit/rtems/include/rtems/rtems/mp.h
+++ b/cpukit/rtems/include/rtems/rtems/mp.h
@@ -30,14 +30,14 @@ extern "C" {
 #endif
 
 /**
- *  @brief Multiprocessing_Manager_initialization
+ *  @brief Multiprocessing Manager Initialization
  *
  *  This routine performs the initialization necessary for this manager.
  */
 void _Multiprocessing_Manager_initialization ( void );
 
 /**
- *  @brief rtems_multiprocessing_announce
+ *  @brief RTEMS Multiprocessing Announce
  *
  *  This routine implements the MULTIPROCESSING_ANNOUNCE directive.
  *  It is invoked by the MPCI layer to indicate that an MPCI packet
diff --git a/cpukit/rtems/include/rtems/rtems/object.h b/cpukit/rtems/include/rtems/rtems/object.h
index 94a52978a8..ced287f8b7 100644
--- a/cpukit/rtems/include/rtems/rtems/object.h
+++ b/cpukit/rtems/include/rtems/rtems/object.h
@@ -89,7 +89,7 @@ typedef struct {
   _Objects_Build_name( _C1, _C2, _C3, _C4 )
 
 /**
- *  @brief Obtain name of object
+ *  @brief Obtain Name of Object
  *
  *  This directive returns the name associated with the specified
  *  object ID.
diff --git a/cpukit/rtems/include/rtems/rtems/part.h b/cpukit/rtems/include/rtems/rtems/part.h
index 8415f9ca5b..b6b5b3a3dc 100644
--- a/cpukit/rtems/include/rtems/rtems/part.h
+++ b/cpukit/rtems/include/rtems/rtems/part.h
@@ -145,11 +145,16 @@ rtems_status_code rtems_partition_delete(
 );
 
 /**
- *  @brief rtems_partition_get_buffer
+ *  @brief RTEMS Get Partition Buffer
  *
  *  This routine implements the rtems_partition_get_buffer directive.  It
  *  attempts to allocate a buffer from the partition associated with ID.
  *  If a buffer is allocated, its address is returned in buffer.
+ * 
+ *  @param[in] id is the partition id
+ *  @param[out] buffer is the pointer to buffer address
+ * 
+ *  @return RTEMS_SUCCESSFUL if successful or error code if unsuccessful
  */
 rtems_status_code rtems_partition_get_buffer(
   rtems_id   id,
diff --git a/cpukit/rtems/include/rtems/rtems/region.h b/cpukit/rtems/include/rtems/rtems/region.h
index a35acf97e2..61162cbb99 100644
--- a/cpukit/rtems/include/rtems/rtems/region.h
+++ b/cpukit/rtems/include/rtems/rtems/region.h
@@ -207,7 +207,7 @@ rtems_status_code rtems_region_get_segment_size(
 );
 
 /**
- *  @brief rtems_region_return_segment
+ *  @brief RTEMS Return Region Segment
  *
  *  This routine implements the rtems_region_return_segment directive.  It
  *  frees the segment to the region associated with ID.  The segment must
@@ -216,6 +216,11 @@ rtems_status_code rtems_region_get_segment_size(
  *  rtems_region_get_segment of the first blocked task, then that task and as
  *  many subsequent tasks as possible will be unblocked with their requests
  *  satisfied.
+ *  
+ *  @param[in] id is the region id
+ *  @param[in] segment is the pointer to segment address
+ * 
+ *  @return RTEMS_SUCCESSFUL if successful or error code if unsuccessful
  */
 rtems_status_code rtems_region_return_segment(
   rtems_id    id,
diff --git a/cpukit/rtems/include/rtems/rtems/regionmp.h b/cpukit/rtems/include/rtems/rtems/regionmp.h
index 7465bbfd4f..f4adc2bda1 100644
--- a/cpukit/rtems/include/rtems/rtems/regionmp.h
+++ b/cpukit/rtems/include/rtems/rtems/regionmp.h
@@ -65,7 +65,7 @@ typedef struct {
 }   Region_MP_Packet;
 
 /**
- *  @brief _Region_MP_Send_process_packet
+ *  @brief Region MP Send Process Packet
  *
  *  This routine performs a remote procedure call so that a
  *  process operation can be performed on another node.
@@ -78,7 +78,7 @@ void _Region_MP_Send_process_packet (
 );
 
 /**
- *  @brief _Region_MP_Send_request_packet
+ *  @brief Region MP Send Request Packet
  *
  *  This routine performs a remote procedure call so that a
  *  directive operation can be initiated on another node.
@@ -93,7 +93,7 @@ rtems_status_code _Region_MP_Send_request_packet (
 );
 
 /**
- *  @brief _Region_MP_Send_response_packet
+ *  @brief Region MP Send Response Packet
  *
  *  This routine performs a remote procedure call so that a
  *  directive can be performed on another node.
@@ -105,7 +105,7 @@ void _Region_MP_Send_response_packet (
 );
 
 /**
- *  @brief _Region_MP_Process_packet
+ *  @brief Region MP Process Packet
  *
  *  This routine performs the actions specific to this package for
  *  the request from another node.
@@ -126,7 +126,7 @@ void _Region_MP_Process_packet (
  */
 
 /**
- *  @brief _Region_MP_Send_extract_proxy
+ *  @brief Region MP Send Extract Proxy
  *
  *  This routine is invoked when a task is deleted and it
  *  has a proxy which must be removed from a thread queue and
@@ -137,7 +137,7 @@ void _Region_MP_Send_extract_proxy (
 );
 
 /**
- *  @brief _Region_MP_Get_packet
+ *  @brief RegionMP Get Packet
  *
  *  This function is used to obtain a region mp packet.
  */
diff --git a/cpukit/rtems/include/rtems/rtems/signal.h b/cpukit/rtems/include/rtems/rtems/signal.h
index 046842f97f..54359ccfaa 100644
--- a/cpukit/rtems/include/rtems/rtems/signal.h
+++ b/cpukit/rtems/include/rtems/rtems/signal.h
@@ -48,12 +48,18 @@ extern "C" {
 void _Signal_Manager_initialization( void );
 
 /**
- *  @brief rtems_signal_catch
+ *  @brief RTEMS Catch Signal
  *
  *  This routine implements the rtems_signal_catch directive.  This directive
  *  is used to establish asr_handler as the Asynchronous Signal Routine
  *  (RTEMS_ASR) for the calling task.  The asr_handler will execute with a
  *  mode of mode_set.
+ * 
+ *  @param[in] asr_handler is the address of asynchronous signal routine (asr)
+ *              ( NULL indicates asr is invalid )
+ *  @param[in] mode_set is the mode value for asr
+ * 
+ *  @return RTEMS_SUCCESSFUL
  */
 rtems_status_code rtems_signal_catch(
   rtems_asr_entry   asr_handler,
diff --git a/cpukit/rtems/include/rtems/rtems/tasks.h b/cpukit/rtems/include/rtems/rtems/tasks.h
index b6b1c1c5b2..03795d5e37 100644
--- a/cpukit/rtems/include/rtems/rtems/tasks.h
+++ b/cpukit/rtems/include/rtems/rtems/tasks.h
@@ -44,6 +44,8 @@
 #include <rtems/rtems/status.h>
 
 /**
+ *  @brief Instantiate RTEMS Classic API Tasks Data
+ * 
  *  This constant is defined to extern most of the time when using
  *  this header file.  However by defining it to nothing, the data
  *  declared in this header file can be instantiated.  This is done
@@ -303,11 +305,17 @@ rtems_status_code rtems_task_delete(
 );
 
 /**
- *  @brief rtems_task_get_note
+ *  @brief RTEMS Get Task Node
  *
  *  This routine implements the rtems_task_get_note directive.  The
  *  value of the indicated notepad for the task associated with ID
  *  is returned in note.
+ * 
+ *  @param[in] id is the thread id
+ *  @param[in] notepad is the notepad number
+ *  @param[out] note is the pointer to note
+ * 
+ *  @return RTEMS_SUCCESSFUL if successful or error code if unsuccessful
  */
 rtems_status_code rtems_task_get_note(
   rtems_id    id,
@@ -343,11 +351,16 @@ rtems_status_code rtems_task_mode(
 );
 
 /**
- *  @brief rtems_task_restart
+ *  @brief RTEMS Task Restart
  *
  *  This routine implements the rtems_task_restart directive.  The
  *  task associated with ID is restarted at its initial entry
  *  point with the new argument.
+ * 
+ *  @param[in] id is the thread id
+ *  @param[in] arg is the thread argument
+ * 
+ *  @return RTEMS_SUCCESSFUL if successful or error code if unsuccessful
  */
 rtems_status_code rtems_task_restart(
   rtems_id   id,
@@ -480,7 +493,7 @@ rtems_status_code rtems_task_variable_delete(
 );
 
 /**
- *  @brief rtems_task_self
+ *  @brief RTEMS Get Self Task Id
  *
  *  This directive returns the ID of the currently executing task.
  */
diff --git a/cpukit/rtems/include/rtems/rtems/timer.h b/cpukit/rtems/include/rtems/rtems/timer.h
index 982f5dabd0..b75a474358 100644
--- a/cpukit/rtems/include/rtems/rtems/timer.h
+++ b/cpukit/rtems/include/rtems/rtems/timer.h
@@ -227,11 +227,16 @@ RTEMS_TIMER_EXTERN Objects_Information  _Timer_Information;
 void _Timer_Manager_initialization(void);
 
 /**
- *  @brief rtems_timer_create
+ *  @brief RTEMS Create Timer
  *
  *  This routine implements the rtems_timer_create directive.  The
  *  timer will have the name name.  It returns the id of the
  *  created timer in ID.
+ * 
+ *  @param[in] name is the timer name
+ *  @param[out] id is the pointer to timer id
+ * 
+ *  @return RTEMS_SUCCESSFUL if successful or error code if unsuccessful
  */
 rtems_status_code rtems_timer_create(
   rtems_name    name,