score misc: Clean up Doxygen #12 (GCI 2012)

This patch is a task from GCI 2012 which improves the Doxygen
comments in the RTEMS source.

http://www.google-melange.com/gci/task/view/google/gci2012/8025203

10 files changed, 111 insertions, 42 deletions

diff --git a/cpukit/rtems/include/rtems/rtems/event.h b/cpukit/rtems/include/rtems/rtems/event.h
index 9b43f7921c..4dab0ec16c 100644
--- a/cpukit/rtems/include/rtems/rtems/event.h
+++ b/cpukit/rtems/include/rtems/rtems/event.h
@@ -435,6 +435,11 @@ typedef struct {
  */
 #define EVENT_CURRENT  0
 
+/**
+ *  @brief Event Manager Initialization
+ *
+ *  This routine performs the initialization necessary for this manager.
+ */
 void _Event_Manager_initialization( void );
 
 void _Event_Seize(
diff --git a/cpukit/rtems/include/rtems/rtems/intr.h b/cpukit/rtems/include/rtems/rtems/intr.h
index 8a6e3b714f..66684fe327 100644
--- a/cpukit/rtems/include/rtems/rtems/intr.h
+++ b/cpukit/rtems/include/rtems/rtems/intr.h
@@ -63,11 +63,18 @@ typedef rtems_isr ( *rtems_isr_entry )(
              );
 
 /**
- *  @brief Implementation of the rtems_interrupt_catch directive.
+ *  @brief RTEMS Interrupt Catch
  *
  *  This directive installs @a new_isr_handler as the RTEMS interrupt service
  *  routine for the interrupt vector with number @a vector.  The previous RTEMS
  *  interrupt service routine is returned in @a old_isr_handler.
+ *  
+ *  @param[in] new_isr_handler is the address of interrupt service routine
+ *  @param[in] vector is the interrupt vector number
+ *  @param[in] old_isr_handler address at which to store previous ISR address
+ * 
+ *  @return RTEMS_SUCCESSFUL and *old_isr_handler filled with previous ISR
+ * 		address
  */
 rtems_status_code rtems_interrupt_catch(
   rtems_isr_entry      new_isr_handler,
@@ -77,8 +84,7 @@ rtems_status_code rtems_interrupt_catch(
 #endif
 
 /**
- *  @brief Disables all maskable interrupts and returns the previous level in
- *  @a _isr_cookie.
+ *  @brief Disable RTEMS Interrupt
  *
  *  @note The interrupt level shall be of type @ref rtems_interrupt_level.
  */
@@ -86,8 +92,7 @@ rtems_status_code rtems_interrupt_catch(
     _ISR_Disable(_isr_cookie)
 
 /**
- *  @brief Enables maskable interrupts to the level indicated by @a
- *  _isr_cookie.
+ *  @brief Enable RTEMS Interrupt
  *
  *  @note The interrupt level shall be of type @ref rtems_interrupt_level.
  */
@@ -95,8 +100,7 @@ rtems_status_code rtems_interrupt_catch(
     _ISR_Enable(_isr_cookie)
 
 /**
- *  @brief Temporarily enables maskable interrupts to the level in @a
- *  _isr_cookie before redisabling them.
+ *  @brief Flash RTEMS Interrupt
  *
  *  @note The interrupt level shall be of type @ref rtems_interrupt_level.
  */
@@ -104,8 +108,7 @@ rtems_status_code rtems_interrupt_catch(
     _ISR_Flash(_isr_cookie)
 
 /**
- *  @brief Returns true if the processor is currently servicing an interrupt
- *  and false otherwise.
+ *  @brief RTEMS Interrupt Is in Progress
  *
  *  A return value of true indicates that the caller is an interrupt service
  *  routine and @b not a thread.  The directives available to an interrupt
diff --git a/cpukit/rtems/include/rtems/rtems/message.h b/cpukit/rtems/include/rtems/rtems/message.h
index 130ea3142c..31844d6afa 100644
--- a/cpukit/rtems/include/rtems/rtems/message.h
+++ b/cpukit/rtems/include/rtems/rtems/message.h
@@ -168,13 +168,19 @@ rtems_status_code rtems_message_queue_send(
 );
 
 /**
- *  @brief rtems_message_queue_urgent
+ *  @brief RTEMS Urgent Message Queue
  *
  *  This routine implements the rtems_message_queue_urgent directive.
  *  This directive has the same behavior as rtems_message_queue_send
  *  except that if no tasks are waiting, the message buffer will
  *  be placed at the FRONT of the chain of pending messages rather
  *  than at the REAR.
+ * 
+ *  @param[in] id is the pointer to message queue
+ *  @param[in] buffer is the pointer to message buffer
+ *  @param[in] size is the size of message to send urgently
+ * 
+ *  @return RTEMS_SUCCESSFUL if successful or error code if unsuccessful
  */
 rtems_status_code rtems_message_queue_urgent(
   rtems_id    id,
@@ -183,12 +189,20 @@ rtems_status_code rtems_message_queue_urgent(
 );
 
 /**
- *  @brief rtems_message_queue_broadcast
+ *  @brief RTEMS Broadcast Message Queue
  *
  *  This routine implements the rtems_message_queue_broadcast directive.
  *  This directive sends the message buffer to all of the tasks blocked
  *  waiting for a message on the message queue indicated by ID.
  *  If no tasks are waiting, then the message buffer will not be queued.
+ * 
+ *  @param[in] id is the pointer to message queue
+ *  @param[in] buffer is the pointer to message buffer
+ *  @param[in] size is the size of message to broadcast
+ *  @param[in] count pointer to area to store number of threads made ready
+ * 
+ *  @return RTEMS_SUCCESSFUL if successful or error code if unsuccessful and
+ *  		*count filled in with number of threads made ready 
  */
 rtems_status_code rtems_message_queue_broadcast(
   rtems_id    id,
diff --git a/cpukit/rtems/include/rtems/rtems/part.h b/cpukit/rtems/include/rtems/rtems/part.h
index c30bc419d6..8415f9ca5b 100644
--- a/cpukit/rtems/include/rtems/rtems/part.h
+++ b/cpukit/rtems/include/rtems/rtems/part.h
@@ -111,7 +111,7 @@ rtems_status_code rtems_partition_create(
 );
 
 /**
- *  @brief rtems_partition_ident
+ *  @brief RTEMS Partition Ident
  *
  *  This routine implements the rtems_partition_ident directive.
  *  This directive returns the partition ID associated with name.
@@ -120,6 +120,13 @@ rtems_status_code rtems_partition_create(
  *  extent of the search for the ID of the partition named name.
  *  The search can be limited to a particular node or allowed to
  *  encompass all nodes.
+ * 
+ *  @param[in] name is the user defined partition name
+ *  @param[in] node is(are) the node(s) to be searched
+ *  @param[in] id is the pointer to partition id
+ * 
+ *  @return RTEMS_SUCCESSFUL if successful or error code if unsuccessful and
+ *  		*id filled in with the partition id
  */
 rtems_status_code rtems_partition_ident(
   rtems_name  name,
diff --git a/cpukit/rtems/include/rtems/rtems/ratemon.h b/cpukit/rtems/include/rtems/rtems/ratemon.h
index c7193a08f8..c3892092d3 100644
--- a/cpukit/rtems/include/rtems/rtems/ratemon.h
+++ b/cpukit/rtems/include/rtems/rtems/ratemon.h
@@ -391,7 +391,7 @@ rtems_status_code rtems_rate_monotonic_period(
 );
 
 /**
- *  @brief _Rate_monotonic_Timeout
+ *  @brief Rate Monotonic Timeout
  *
  *  This routine is invoked when the period represented
  *  by ID expires.  If the thread which owns this period is blocked
@@ -399,6 +399,8 @@ rtems_status_code rtems_rate_monotonic_period(
  *  period is restarted.  If the owning thread is not waiting for the
  *  period to expire, then the period is placed in the EXPIRED
  *  state and not restarted.
+ * 
+ *  @param[in] id is the period id
  */
 void _Rate_monotonic_Timeout(
   rtems_id    id,
diff --git a/cpukit/rtems/include/rtems/rtems/region.h b/cpukit/rtems/include/rtems/rtems/region.h
index 12bba85985..c14c3489b6 100644
--- a/cpukit/rtems/include/rtems/rtems/region.h
+++ b/cpukit/rtems/include/rtems/rtems/region.h
@@ -217,7 +217,7 @@ rtems_status_code rtems_region_return_segment(
 );
 
 /**
- *  @brief rtems_region_resize_segment
+ *  @brief Resize RTEMS Region Segment
  *
  *  This routine implements the rtems_region_resize_segment directive.  It
  *  tries to resize segment in the region associated with 'id' to the new size
@@ -228,13 +228,16 @@ rtems_status_code rtems_region_return_segment(
  *  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.
- *  Returns:
- *    RTEMS_SUCCESSFUL  - operation successful
- *    RTEMS_UNSATISFIED - the segment can't be resized in place
- *    any other code    - failure.
- *  On RTEMS_SUCCESSFUL or RTEMS_UNSATISFIED exit it returns into the
- *  'old_size' the old size in bytes of the user memory area of the specified
- *  segment.
+ * 
+ *  @param[in] id is the region id
+ *  @param[in] segmet is the pointer to segment address
+ *  @param[in] size is the new required size
+ *  @return RTEMS_SUCCESSFUL if operation successful, RTEMS_UNSATISFIED if the
+ * 	the segment can't be resized in place or any other code atfailure
+ * 
+ *  @note On RTEMS_SUCCESSFUL or RTEMS_UNSATISFIED exit it returns into the
+ *  	'old_size' the old size in bytes of the user memory area of the 
+ * 	specified segment.
  */
 rtems_status_code rtems_region_resize_segment(
   rtems_id    id,
diff --git a/cpukit/rtems/include/rtems/rtems/sem.h b/cpukit/rtems/include/rtems/rtems/sem.h
index c15d9eede2..4475d030c2 100644
--- a/cpukit/rtems/include/rtems/rtems/sem.h
+++ b/cpukit/rtems/include/rtems/rtems/sem.h
@@ -185,8 +185,18 @@ rtems_status_code rtems_semaphore_release(
 );
 
 /**
- *  @brief rtems_semaphore_flush
+ *  @brief RTEMS Semaphore Flush
+ * 
+ *  DESCRIPTION:
+ *  This package is the implementation of the flush directive
+ *  of the Semaphore Manager.
+ * 
+ *  This directive allows a thread to flush the threads
  *  pending on the semaphore.
+ *
+ *  @param[in] id is the semaphore id
+ * 
+ *  @return RTEMS_SUCCESSFUL if successful or error code if unsuccessful
  */
 rtems_status_code rtems_semaphore_flush(
   rtems_id	   id
diff --git a/cpukit/rtems/include/rtems/rtems/semmp.h b/cpukit/rtems/include/rtems/rtems/semmp.h
index 1fc3d4af31..d592d33b3a 100644
--- a/cpukit/rtems/include/rtems/rtems/semmp.h
+++ b/cpukit/rtems/include/rtems/rtems/semmp.h
@@ -63,7 +63,7 @@ typedef struct {
 }   Semaphore_MP_Packet;
 
 /**
- *  @brief Semaphore_MP_Send_process_packet
+ *  @brief Semaphore MP Send Process Packet
  *
  *  This routine performs a remote procedure call so that a
  *  process operation can be performed on another node.
@@ -76,7 +76,7 @@ void _Semaphore_MP_Send_process_packet (
 );
 
 /**
- *  @brief Semaphore_MP_Send_request_packet
+ *  @brief Semaphore MP Send Request Packet
  *
  *  This routine performs a remote procedure call so that a
  *  directive operation can be initiated on another node.
@@ -89,7 +89,7 @@ rtems_status_code _Semaphore_MP_Send_request_packet (
 );
 
 /**
- *  @brief Semaphore_MP_Send_response_packet
+ *  @brief Semaphore MP Send Response Packet
  *
  *  This routine performs a remote procedure call so that a
  *  directive can be performed on another node.
@@ -101,7 +101,7 @@ void _Semaphore_MP_Send_response_packet (
 );
 
 /**
- *  @brief Semaphore_MP_Process_packet
+ *  @brief Semaphore MP Process Packet
  *
  *  This routine performs the actions specific to this package for
  *  the request from another node.
@@ -111,7 +111,7 @@ void _Semaphore_MP_Process_packet (
 );
 
 /**
- *  @brief Semaphore_MP_Send_object_was_deleted
+ *  @brief Semaphore MP Send Object was Deleted
  *
  *  This routine is invoked indirectly by the thread queue
  *  when a proxy has been removed from the thread queue and
@@ -122,7 +122,7 @@ void _Semaphore_MP_Send_object_was_deleted (
 );
 
 /**
- *  @brief Semaphore_MP_Send_extract_proxy
+ *  @brief Semaphore 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
@@ -133,18 +133,21 @@ void _Semaphore_MP_Send_extract_proxy (
 );
 
 /**
- *  @brief Semaphore_MP_Get_packet
+ *  @brief Semaphore MP Get Packet
  *
  *  This function is used to obtain a semaphore mp packet.
  */
 Semaphore_MP_Packet *_Semaphore_MP_Get_packet ( void );
 
 /**
- * @brief _Semaphore_Core_mutex_mp_support
+ * @brief Semaphore Core Mutex MP Support
  *
  *  This function processes the global actions necessary for remote
  *  accesses to a global semaphore based on a core mutex.  This function
  *  is called by the core.
+ *
+ *  @param[in] the_thread the remote thread the semaphore was surrendered to
+ *  @param[in] id is the id of the surrendered semaphore
  */
 void  _Semaphore_Core_mutex_mp_support (
   Thread_Control *the_thread,
@@ -152,11 +155,14 @@ void  _Semaphore_Core_mutex_mp_support (
 );
 
 /**
- *  @brief Semaphore_Core_mp_support
+ *  @brief Semaphore Core MP Support
  *
  *  This function processes the global actions necessary for remote
  *  accesses to a global semaphore based on a core semaphore.  This function
  *  is called by the core.
+ *
+ *  @param[in] the_thread the remote thread the semaphore was surrendered to
+ *  @param[in] id is the id of the surrendered semaphore
  */
 void  _Semaphore_Core_semaphore_mp_support (
   Thread_Control *the_thread,
diff --git a/cpukit/rtems/include/rtems/rtems/tasks.h b/cpukit/rtems/include/rtems/rtems/tasks.h
index f141c102e6..e80df03103 100644
--- a/cpukit/rtems/include/rtems/rtems/tasks.h
+++ b/cpukit/rtems/include/rtems/rtems/tasks.h
@@ -240,14 +240,14 @@ RTEMS_TASKS_EXTERN Objects_Information _RTEMS_tasks_Information;
 extern void (*_RTEMS_tasks_Initialize_user_tasks_p)(void);
 
 /**
- *  @brief _RTEMS_tasks_Manager_initialization
+ *  @brief RTEMS Task Manager Initialization
  *
  *  This routine initializes all Task Manager related data structures.
  */
 void _RTEMS_tasks_Manager_initialization(void);
 
 /**
- *  @brief rtems_task_create
+ *  @brief RTEMS Task Create
  *
  *  This routine implements the rtems_task_create directive.  The task
  *  will have the name name.  The attribute_set can be used to indicate
@@ -255,6 +255,16 @@ void _RTEMS_tasks_Manager_initialization(void);
  *  The task's stack will be stack_size bytes.   The task will begin
  *  execution with initial_priority and initial_modes.  It returns the
  *  id of the created task in ID.
+ * 
+ *  @param[in] name is the user defined thread name
+ *  @param[in] initial_priority is the thread priority
+ *  @param[in] stack_size is the stack size in bytes
+ *  @param[in] initial_modes is the initial thread mode
+ *  @param[in] attribute_set is the thread attributes
+ *  @param[in] id is the pointer to thread id
+ * 
+ *  @return RTEMS_SUCCESSFUL if successful or error code if unsuccessful
+ *  		and *id thread id filled in
  */
 rtems_status_code rtems_task_create(
   rtems_name           name,
@@ -392,22 +402,29 @@ rtems_status_code rtems_task_start(
 );
 
 /**
- *  @brief rtems_task_wake_when
+ *  @brief RTEMS Task Wake When
  *
  *  This routine implements the rtems_task_wake_when directive.  The
  *  calling task is blocked until the current time of day is
  *  equal to that indicated by time_buffer.
+ * 
+ *  @param[in] time_buffer is the pointer to the time and date structure
+ * 
+ *  @return RTEMS_SUCCESSFUL if successful or error code if unsuccessful
  */
 rtems_status_code rtems_task_wake_when(
   rtems_time_of_day *time_buffer
 );
 
 /**
- *  @brief rtems_task_wake_after
+ *  @brief RTEMS Task Wake After
  *
  *  This routine implements the rtems_task_wake_after directive.  The
  *  calling task is blocked until the indicated number of clock
  *  ticks have occurred.
+ * 
+ *  @param[in] ticks is the number of ticks to wait
+ *  @return RTEMS_SUCCESSFUL
  */
 rtems_status_code rtems_task_wake_after(
   rtems_interval  ticks
@@ -446,7 +463,7 @@ rtems_status_code rtems_task_variable_get(
 );
 
 /**
- *  @brief rtems_task_variable_delete
+ *  @brief RTEMS Delete Task Variable
  *
  *  This directive removes a per task variable.
  */
@@ -463,14 +480,10 @@ rtems_status_code rtems_task_variable_delete(
 rtems_id rtems_task_self(void);
 
 /**
- *  @brief _RTEMS_tasks_Initialize_user_tasks
+ *  @brief RTEMS User Task Initialization
  *
  *  This routine creates and starts all configured user
  *  initialization threads.
- *
- *  Input parameters: NONE
- *
- *  Output parameters:  NONE
  */
 void _RTEMS_tasks_Initialize_user_tasks( void );
 
diff --git a/cpukit/rtems/include/rtems/rtems/timer.h b/cpukit/rtems/include/rtems/rtems/timer.h
index c0e1e5ba86..ea09bc09d4 100644
--- a/cpukit/rtems/include/rtems/rtems/timer.h
+++ b/cpukit/rtems/include/rtems/rtems/timer.h
@@ -383,10 +383,16 @@ typedef struct {
 } rtems_timer_information;
 
 /**
- *  @brief rtems_timer_get_information
+ *  @brief RTEMS Get Timer Information
  *
  *  This routine implements the rtems_timer_get_information directive.
  *  This directive returns information about the timer.
+ * 
+ *  @param[in] id is the timer id
+ *  @param[in] the_info is the pointer to timer information block
+ * 
+ *  @return RTEMS_SUCCESSFUL if successful or error code if unsuccessful and
+ *  		*the_info region information block filled in
  */
 rtems_status_code rtems_timer_get_information(
   rtems_id                 id,