sapi: Doxygen Clean Up Task #1

12 files changed, 183 insertions, 179 deletions

diff --git a/cpukit/sapi/include/rtems/cbs.h b/cpukit/sapi/include/rtems/cbs.h
index dda56e27b0..e0e619cdeb 100644
--- a/cpukit/sapi/include/rtems/cbs.h
+++ b/cpukit/sapi/include/rtems/cbs.h
@@ -1,5 +1,5 @@
 /**
- * @file rtems/cbs.h
+ * @file
  *
  * @brief Constants and Structures Associated
  * with the CBS library in RTEMS
diff --git a/cpukit/sapi/include/rtems/chain.h b/cpukit/sapi/include/rtems/chain.h
index 12d6e3b536..e1644acd14 100644
--- a/cpukit/sapi/include/rtems/chain.h
+++ b/cpukit/sapi/include/rtems/chain.h
@@ -1,9 +1,7 @@
 /**
  * @file
- *
- * @ingroup ClassicChains
- *
- * @brief Chain API.
+ * 
+ * @brief Chain API
  */
 
 /*
@@ -33,7 +31,7 @@ extern "C" {
  *
  * @ingroup ClassicRTEMS
  *
- * @brief Chain API.
+ * @brief Chain API
  *
  * @{
  */
diff --git a/cpukit/sapi/include/rtems/config.h b/cpukit/sapi/include/rtems/config.h
index 9a35437b4f..58d2d92fb5 100644
--- a/cpukit/sapi/include/rtems/config.h
+++ b/cpukit/sapi/include/rtems/config.h
@@ -1,5 +1,5 @@
 /**
- * @file rtems/config.h
+ * @file
  *
  * @brief Table of User Defined Configuration Parameters
  *
@@ -79,9 +79,10 @@ typedef struct {
   /** This is the maximum number of proxies. */
   uint32_t            maximum_proxies;
 
-  /** The MPCI Receive server is assumed to have a stack of at least
-   *  minimum stack size.  This field specifies the amount of extra
-   *  stack this task will be given in bytes.
+  /** 
+   * The MPCI Receive server is assumed to have a stack of at least
+   * minimum stack size.  This field specifies the amount of extra
+   * stack this task will be given in bytes.
    */
   uint32_t            extra_mpci_receive_server_stack;
 
@@ -93,14 +94,14 @@ typedef struct {
 /**
  * @brief Task stack allocator initialization hook.
  *
- * @param[in] stack_space_size Size of the stack space in bytes.
+ * @param[in] stack_space_size is the size of the stack space in bytes.
  */
 typedef void (*rtems_stack_allocate_init_hook)( size_t stack_space_size );
 
 /**
  * @brief Task stack allocator hook.
  *
- * @param[in] stack_size Size of the task stack in bytes.
+ * @param[in] stack_size is the Size of the task stack in bytes.
  *
  * @retval NULL Not enough memory.
  * @retval other Pointer to task stack.
@@ -110,7 +111,7 @@ typedef void *(*rtems_stack_allocate_hook)( size_t stack_size );
 /**
  * @brief Task stack deallocator hook.
  *
- * @param[in] addr Pointer to previously allocated task stack.
+ * @param[in] addr is a pointer to previously allocated task stack.
  */
 typedef void (*rtems_stack_free_hook)( void *addr );
 
@@ -126,49 +127,58 @@ typedef void (*rtems_stack_free_hook)( void *addr );
  *     + required number of each object type for each API configured
  */
 typedef struct {
-  /** This field specifies the size in bytes of the RTEMS Workspace.
+  /**
+   * This field specifies the size in bytes of the RTEMS Workspace.
    */
   uintptr_t                      work_space_size;
 
-  /** This field specifies the size in bytes of the RTEMS thread stack space.
+  /**
+   * This field specifies the size in bytes of the RTEMS thread stack space.
    */
   uintptr_t                      stack_space_size;
 
-  /** This field specifies the maximum number of dynamically installed
-   *  used extensions.
+  /** 
+   * This field specifies the maximum number of dynamically installed
+   * used extensions.
    */
   uint32_t                       maximum_extensions;
 
-  /** This field specifies the number of microseconds which elapse
-   *  between clock ticks.  This is the basis for RTEMS timing.
+  /** 
+   * This field specifies the number of microseconds which elapse
+   * between clock ticks.  This is the basis for RTEMS timing.
    */
   uint32_t                       microseconds_per_tick;
 
-  /** This field specifies the number of nanoseconds which elapse
-   *  between clock ticks.  This value is derived from the
-   *  microseconds_per_tick field and provided to avoid calculation at
-   *  run-time.
+  /** 
+   * This field specifies the number of nanoseconds which elapse
+   * between clock ticks.  This value is derived from the
+   * microseconds_per_tick field and provided to avoid calculation at
+   * run-time.
    */
   uint32_t                       nanoseconds_per_tick;
 
-  /** This field specifies the number of ticks in each task's timeslice.
+  /** 
+   * This field specifies the number of ticks in each task's timeslice.
    */
   uint32_t                       ticks_per_timeslice;
 
-  /** This element points to the BSP's optional idle task which may override
-   *  the default one provided with RTEMS.
+  /** 
+   * This element points to the BSP's optional idle task which may override
+   * the default one provided with RTEMS.
    */
   Thread                       (*idle_task)( uintptr_t );
 
-  /** This field specifies the size of the IDLE task's stack.  If less than or
-   *  equal to the minimum stack size, then the IDLE task will have the minimum
-   *  stack size.
+  /** 
+   * This field specifies the size of the IDLE task's stack.  If less than or
+   * equal to the minimum stack size, then the IDLE task will have the minimum
+   * stack size.
    */
   uint32_t                       idle_task_stack_size;
 
-  /** This field specifies the size of the interrupt stack.  If less than or
-   *  equal to the minimum stack size, then the interrupt stack will be of
-   *  minimum stack size.
+  /** 
+   * This field specifies the size of the interrupt stack.  If less than or
+   * equal to the minimum stack size, then the interrupt stack will be of
+   * minimum stack size.
    */
   uint32_t                       interrupt_stack_size;
 
@@ -187,10 +197,11 @@ typedef struct {
    */
   rtems_stack_free_hook          stack_free_hook;
 
-  /** If this element is TRUE, then RTEMS will zero the Executive Workspace.
-   *  When this element is FALSE, it is assumed that the BSP or invoking
-   *  environment has ensured that memory was cleared before RTEMS was
-   *  invoked.
+  /** 
+   * If this element is TRUE, then RTEMS will zero the Executive Workspace.
+   * When this element is FALSE, it is assumed that the BSP or invoking
+   * environment has ensured that memory was cleared before RTEMS was
+   * invoked.
    */
   bool                           do_zero_of_workspace;
 
@@ -222,23 +233,23 @@ typedef struct {
 } rtems_configuration_table;
 
 /**
- *   This is the configuration table generated by confdefs.h.
+ * This is the configuration table generated by confdefs.h.
  */
 extern const rtems_configuration_table Configuration;
 
 #if defined(RTEMS_MULTIPROCESSING)
   /**
-   *   This points to the multiprocessing configuration table.
+   *  This points to the multiprocessing configuration table.
    */
   SAPI_EXTERN rtems_multiprocessing_table  *_Configuration_MP_table;
 #endif
 
 #if defined(RTEMS_MULTIPROCESSING)
   /**
-   *  @brief RTEMS Multiprocessing Configuration Table
+   * @brief RTEMS multiprocessing configuration table.
    *
-   *  This is the RTEMS Multiprocessing Configuration Table expected to
-   *  be generated by confdefs.h.
+   * This is the RTEMS Multiprocessing Configuration Table expected to
+   * be generated by confdefs.h.
    */
   extern rtems_multiprocessing_table  Multiprocessing_configuration;
 #endif
@@ -294,7 +305,7 @@ extern const rtems_configuration_table Configuration;
 #define rtems_configuration_get_stack_free_hook() \
         (Configuration.stack_free_hook)
 
-/**
+ /**
   * This macro assists in accessing the field which indicates whether
   * RTEMS is responsible for zeroing the Executive Workspace.
   */
diff --git a/cpukit/sapi/include/rtems/extension.h b/cpukit/sapi/include/rtems/extension.h
index 3d54092a8c..d57646ca9e 100644
--- a/cpukit/sapi/include/rtems/extension.h
+++ b/cpukit/sapi/include/rtems/extension.h
@@ -1,8 +1,6 @@
 /**
  * @file
- *
- * @ingroup ClassicUserExtensions
- *
+ * 
  * @brief User Extensions API.
  */
 
@@ -39,7 +37,7 @@ typedef struct {
 }   Extension_Control;
 
 /**
- *  @brief Initialize Extension Manager
+ *  @brief Initialize extension manager.
  *
  *  This routine initializes all extension manager related data structures.
  */
diff --git a/cpukit/sapi/include/rtems/fatal.h b/cpukit/sapi/include/rtems/fatal.h
index 46a7ab9574..7ef9f71ba6 100644
--- a/cpukit/sapi/include/rtems/fatal.h
+++ b/cpukit/sapi/include/rtems/fatal.h
@@ -1,8 +1,6 @@
 /**
  * @file
  *
- * @ingroup ClassicFatal
- *
  * @brief Fatal API.
  */
 
@@ -42,9 +40,9 @@ extern "C" {
 typedef CPU_Exception_frame rtems_exception_frame;
 
 /**
- *  @brief Prints the exception frame via printk().
+ * @brief Prints the exception frame via printk().
  *
- *  @see rtems_fatal() and RTEMS_FATAL_SOURCE_EXCEPTION.
+ * @see rtems_fatal() and RTEMS_FATAL_SOURCE_EXCEPTION.
  */
 static inline void rtems_exception_frame_print(
   const rtems_exception_frame *frame
@@ -57,9 +55,7 @@ static inline void rtems_exception_frame_print(
  * @brief Invokes the internal error handler with a source of
  * INTERNAL_ERROR_RTEMS_API and is internal set to false.
  *
- * @param[in] the_error A 32-bit fatal error code.
- *
- * @return This function will not return.
+ * @param[in] the_error is a 32-bit fatal error code.
  *
  * @see _Internal_error_Occurred().
  */
@@ -70,10 +66,8 @@ void rtems_fatal_error_occurred(
 /**
  * @brief Invokes the internal error handler with is internal set to false.
  *
- * @param[in] source The fatal source.
- * @param[in] error The fatal code.
- *
- * @return This function will not return.
+ * @param[in] source is the fatal source.
+ * @param[in] error is the fatal code.
  *
  * @see _Internal_error_Occurred().
  */
@@ -85,20 +79,20 @@ void rtems_fatal(
 /**
  * @brief Returns a description for a fatal source.
  *
- * @param[in] source The fatal source.
+ * @param[in] source is the fatal source.
  *
- * @return The fatal source description or "?" in case the passed fatal source
- * is invalid.
+ * @retval description The fatal source description.
+ * @retval ? The passed fatal source is invalid.
  */
 const char *rtems_fatal_source_description( rtems_fatal_source source );
 
 /**
  * @brief Returns a description for an internal error code.
  *
- * @param[in] error The error code.
+ * @param[in] error is the error code.
  *
- * @return The error code description or "?" in case the passed error code is
- * invalid.
+ * @retval description The error code description.
+ * @retval ? The passed error code is invalid.
  */
 const char *rtems_internal_error_description( rtems_fatal_code error );
 
diff --git a/cpukit/sapi/include/rtems/init.h b/cpukit/sapi/include/rtems/init.h
index d357c113df..ad9a144910 100644
--- a/cpukit/sapi/include/rtems/init.h
+++ b/cpukit/sapi/include/rtems/init.h
@@ -1,19 +1,19 @@
 /**
- * @file rtems/init.h
+ * @file
  *
  * @brief Constants and Structures Associated
  * with the Initialization Manager
  *
- *  This include file contains all the constants and structures associated
- *  with the Initialization Manager.  This manager is responsible for
- *  initializing RTEMS, creating and starting all configured initialization
- *  tasks, invoking the initialization routine for each user-supplied device
- *  driver, and initializing the optional multiprocessor layer.
+ * This include file contains all the constants and structures associated
+ * with the Initialization Manager.  This manager is responsible for
+ * initializing RTEMS, creating and starting all configured initialization
+ * tasks, invoking the initialization routine for each user-supplied device
+ * driver, and initializing the optional multiprocessor layer.
  *
- *  This manager provides directives to:
+ * This manager provides directives to:
  *
- *     + initialize the RTEMS executive
- *     + shutdown the RTEMS executive
+ *    + initialize the RTEMS executive
+ *    + shutdown the RTEMS executive
  */
 
 /*
@@ -38,64 +38,64 @@ extern "C" {
 
 #if defined(RTEMS_MULTIPROCESSING)
 /**
- *  The following defines the default Multiprocessing Configuration
- *  Table.  This table is used in a single processor system.
+ * The following defines the default Multiprocessing Configuration
+ * Table.  This table is used in a single processor system.
  */
 extern const rtems_multiprocessing_table
   _Initialization_Default_multiprocessing_table;
 #endif
 
 /**
- *  @brief rtems_initialize_data_structures
+ * @brief RTEMS data structures initialization.
  *
- *  This routine implements the portion of the RTEMS initializatin process
- *  that involves initializing data structures to a state that scheduling
- *  can occur in a consistent manner.
+ * This routine implements the portion of the RTEMS initializatin process
+ * that involves initializing data structures to a state that scheduling
+ * can occur in a consistent manner.
  */
 void rtems_initialize_data_structures(void);
 
 /**
- *  @brief rtems_initialize_before_drivers
+ * @brief RTEMS initialization before the device drivers are initialized.
  *
- *  This routine implements the portion of RTEMS initialization that
- *  is done immediately before device drivers are initialized.
+ * This routine implements the portion of RTEMS initialization that
+ * is done immediately before device drivers are initialized.
  */
 void rtems_initialize_before_drivers(void);
 
 /**
- *  @brief rtems_initialize_device_drivers
+ * @brief RTEMS initialization that initializes all device drivers.
  *
- *  This routine implements the portion of RTEMS initialization that
- *  initializes all device drivers.
+ * This routine implements the portion of RTEMS initialization that
+ * initializes all device drivers.
  */
 void rtems_initialize_device_drivers(void);
 
 /**
- *  @brief Starts the multitasking.
+ * @brief Starts the multitasking.
  *
- *  This directive initiates multitasking and performs a context switch to the
- *  first user application task and may enable interrupts as a side-effect of
- *  that context switch.  The context switch saves the executing context.  The
- *  application runs now.  The directive rtems_shutdown_executive() will return
- *  to the saved context.  The exit() function will use this directive.
+ * This directive initiates multitasking and performs a context switch to the
+ * first user application task and may enable interrupts as a side-effect of
+ * that context switch.  The context switch saves the executing context.  The
+ * application runs now.  The directive rtems_shutdown_executive() will return
+ * to the saved context.  The exit() function will use this directive.
  *
- *  After a return to the saved context a fatal system state is reached.  The
- *  fatal source is RTEMS_FATAL_SOURCE_EXIT with a fatal code set to the value
- *  passed to rtems_shutdown_executive().
+ * After a return to the saved context a fatal system state is reached.  The
+ * fatal source is RTEMS_FATAL_SOURCE_EXIT with a fatal code set to the value
+ * passed to rtems_shutdown_executive().
  *
- *  This directive does not return.
+ * This directive does not return.
  */
 void rtems_initialize_start_multitasking(void)
   RTEMS_COMPILER_NO_RETURN_ATTRIBUTE;
 
 /**
- *  @brief Shutdown the RTEMS environment
+ * @brief Shutdown the RTEMS environment.
  *
- *  This routine implements the rtems_shutdown_executive directive.  The
- *  invocation of this directive results in the RTEMS environment being
- *  shutdown and multitasking halted.  From the application's perspective,
- *  invocation of this directive results in the rtems_initialize_executive
- *  directive exitting to the startup code which invoked it.
+ * This routine implements the rtems_shutdown_executive directive.  The
+ * invocation of this directive results in the RTEMS environment being
+ * shutdown and multitasking halted.  From the application's perspective,
+ * invocation of this directive results in the rtems_initialize_executive
+ * directive exitting to the startup code which invoked it.
  */
 void rtems_shutdown_executive(
   uint32_t   result
diff --git a/cpukit/sapi/include/rtems/io.h b/cpukit/sapi/include/rtems/io.h
index 8f02a34e2c..6901d84039 100644
--- a/cpukit/sapi/include/rtems/io.h
+++ b/cpukit/sapi/include/rtems/io.h
@@ -101,13 +101,13 @@ rtems_status_code rtems_io_register_driver(
 );
 
 /**
- *  @brief Unregister a Driver from the Device Driver Table.
+ * @brief Unregister a driver from the device driver table.
  *
- *  @param[in] major is the device major number.
+ * @param[in] major is the device major number.
  *
- *  @retval RTEMS_SUCCESSFUL Device driver successfully unregistered.
- *  @retval RTEMS_UNSATISFIED Invalid major number.
- *  @retval RTEMS_CALLED_FROM_ISR Called from interrupt context.
+ * @retval RTEMS_SUCCESSFUL Device driver successfully unregistered.
+ * @retval RTEMS_UNSATISFIED Invalid major number.
+ * @retval RTEMS_CALLED_FROM_ISR Called from interrupt context.
  */
 rtems_status_code rtems_io_unregister_driver(
   rtems_device_major_number major
@@ -131,15 +131,15 @@ rtems_status_code rtems_io_register_name(
 /** @} */
 
 /**
- *  @brief IO Driver Initialization
+ * @brief IO driver initialization.
  *
- *  This routine is the initialization directive of the IO manager.
+ * This routine is the initialization directive of the IO manager.
  *
- *  @param[in] major is the device drive number
- *  @param[in] minor is the device number
- *  @param[in] argument is the pointer to the argument(s)
+ * @param[in] major is the device drive number
+ * @param[in] minor is the device number
+ * @param[in] argument is the pointer to the argument(s)
  *
- *  @return status code
+ * @return status code
  */
 rtems_status_code rtems_io_initialize(
   rtems_device_major_number  major,
@@ -148,15 +148,15 @@ rtems_status_code rtems_io_initialize(
 );
 
 /**
- *  @brief Opening for The IO Manager
+ * @brief Opening for the IO manager.
  *  
- *  Opens a device driver with the number @a major.
+ * Opens a device driver with the number @a major.
  *
- *  @param[in] major is the device driver number.
- *  @param[in] minor is the device number.
- *  @param[in] argument is the pointer to the argument(s).
+ * @param[in] major is the device driver number.
+ * @param[in] minor is the device number.
+ * @param[in] argument is the pointer to the argument(s).
  *
- *  @return Status code.
+ * @return Status code.
  */
 rtems_status_code rtems_io_open(
   rtems_device_major_number  major,
@@ -165,15 +165,15 @@ rtems_status_code rtems_io_open(
 );
 
 /**
- *  @brief Closing for The IO Manager
+ * @brief Closing for the IO manager.
  *  
- *  This routine is the close directive of the IO manager.
+ * This routine is the close directive of the IO manager.
  *
- *  @param[in] major is the device driver number.
- *  @param[in] minor is the device number.
- *  @param[in] argument is the pointer to the argument(s).
+ * @param[in] major is the device driver number.
+ * @param[in] minor is the device number.
+ * @param[in] argument is the pointer to the argument(s).
  *
- *  @return Status code.
+ * @return Status code.
  */
 rtems_status_code rtems_io_close(
   rtems_device_major_number  major,
@@ -182,15 +182,15 @@ rtems_status_code rtems_io_close(
 );
 
 /**
- *  @brief Reading for The IO Manager
+ * @brief Reading for the IO manager.
  *  
- *  This routine is the read directive of the IO manager.
+ * This routine is the read directive of the IO manager.
  *
- *  @param[in] major is the device driver number.
- *  @param[in] minor is the device number.
- *  @param[in] argument is the pointer to the argument(s).
+ * @param[in] major is the device driver number.
+ * @param[in] minor is the device number.
+ * @param[in] argument is the pointer to the argument(s).
  *
- *  @return Status code.
+ * @return Status code.
  */
 rtems_status_code rtems_io_read(
   rtems_device_major_number  major,
@@ -199,15 +199,15 @@ rtems_status_code rtems_io_read(
 );
 
 /**
- *  @brief Writing for The IO Manager
+ * @brief Writing for the IO manager.
  *  
- *  This routine is the write directive of the IO manager.
+ * This routine is the write directive of the IO manager.
  *
- *  @param[in] major is the device driver number.
- *  @param[in] minor is the device number.
- *  @param[in] argument is the pointer to the argument(s).
+ * @param[in] major is the device driver number.
+ * @param[in] minor is the device number.
+ * @param[in] argument is the pointer to the argument(s).
  *
- *  @return Status code.
+ * @return Status code.
  */
 rtems_status_code rtems_io_write(
   rtems_device_major_number  major,
@@ -216,15 +216,15 @@ rtems_status_code rtems_io_write(
 );
 
 /**
- *  @brief Control for The IO Manager
+ * @brief Control for the IO manager.
  *  
- *  This routine is the control directive of the IO manager.
+ * This routine is the control directive of the IO manager.
  *
- *  @param[in] major is the device driver number.
- *  @param[in] minor is the device number.
- *  @param[in] argument is the pointer to the argument(s).
+ * @param[in] major is the device driver number.
+ * @param[in] minor is the device number.
+ * @param[in] argument is the pointer to the argument(s).
  *
- *  @return Status code.
+ * @return Status code.
  */
 rtems_status_code rtems_io_control(
   rtems_device_major_number  major,
@@ -256,18 +256,18 @@ SAPI_IO_EXTERN uint32_t _IO_Number_of_drivers;
 SAPI_IO_EXTERN rtems_driver_address_table *_IO_Driver_address_table;
 
 /**
- *  @brief Initialization of Device Drivers
+ * @brief Initialization of device drivers.
  *
- *  @note The IO manager has been extended to support runtime driver
- *  registration. The driver table is now allocated in the
- *  workspace.
+ * NOTE: The IO manager has been extended to support runtime driver
+ * registration. The driver table is now allocated in the
+ * workspace.
  */
 void _IO_Manager_initialization( void );
 
 /**
- *  @brief Initialization of All Device Drivers
+ * @brief Initialization of all device drivers.
  *
- *  Initializes all device drivers.
+ * Initializes all device drivers.
  */
 void _IO_Initialize_all_drivers( void );
 
diff --git a/cpukit/sapi/include/rtems/mptables.h b/cpukit/sapi/include/rtems/mptables.h
index 52db445833..fcef585461 100644
--- a/cpukit/sapi/include/rtems/mptables.h
+++ b/cpukit/sapi/include/rtems/mptables.h
@@ -1,5 +1,5 @@
 /**
- * @file rtems/mptables.h
+ * @file
  *
  * @brief Executive's Pre-Initialized Tables used in a
  * Multiprocessor Configuration
diff --git a/cpukit/sapi/include/rtems/rbheap.h b/cpukit/sapi/include/rtems/rbheap.h
index 39bbc69a3f..fb830be2d7 100644
--- a/cpukit/sapi/include/rtems/rbheap.h
+++ b/cpukit/sapi/include/rtems/rbheap.h
@@ -2,8 +2,6 @@
  * @file
  *
  * @brief Red-Black Tree Heap API
- *
- * @ingroup RBHeap
  */
 
 /*
@@ -34,7 +32,7 @@ extern "C" {
 /**
  * @defgroup RBHeap Red-Black Tree Heap
  *
- * @brief Red-Black Tree Heap API.
+ * @brief Red-Black Tree Heap API
  *
  * The red-black tree heap provides a memory allocator suitable to implement
  * the malloc() and free() interface.  It uses a first-fit allocation strategy.
@@ -146,13 +144,13 @@ struct rtems_rbheap_control {
 /**
  * @brief Initializes the red-black tree heap @a control.
  *
- * @param[in, out] control The red-black tree heap.
- * @param[in] area_begin The managed memory area begin.
- * @param[in] area_size The managed memory area size.
- * @param[in] alignment The minimum chunk alignment.
- * @param[in] extend_descriptors The handler to extend the available chunk
+ * @param[in, out] control is the red-black tree heap.
+ * @param[in] area_begin is the managed memory area begin.
+ * @param[in] area_size is the managed memory area size.
+ * @param[in] alignment is the minimum chunk alignment.
+ * @param[in] extend_descriptors is the handler to extend the available chunk
  * descriptors.
- * @param[in] handler_arg The handler argument.
+ * @param[in] handler_arg is the handler argument.
  *
  * @retval RTEMS_SUCCESSFUL Successful operation.
  * @retval RTEMS_INVALID_NUMBER The alignment is not positive.
@@ -175,8 +173,8 @@ rtems_status_code rtems_rbheap_initialize(
  * The chunk begin is aligned by the value specified in
  * rtems_rbheap_initialize().
  *
- * @param[in, out] control The red-black tree heap.
- * @param[in] size The requested chunk size in bytes.
+ * @param[in, out] control is the red-black tree heap.
+ * @param[in] size is the requested chunk size in bytes.
  *
  * @retval NULL Not enough free space in the heap.
  * @retval otherwise Pointer to allocated chunk of memory.
@@ -184,16 +182,17 @@ rtems_status_code rtems_rbheap_initialize(
 void *rtems_rbheap_allocate(rtems_rbheap_control *control, size_t size);
 
 /**
- * @brief Frees a chunk of memory @a ptr allocated from the red-black tree heap
- * @a control.
+ * @brief Frees a chunk of memory @a ptr allocated from the red-black 
+ * tree heap @a control.
  *
- * @param[in, out] control The red-black tree heap.
- * @param[in] ptr The pointer to the chunk of memory.
+ * @param[in, out] control is the red-black tree heap.
+ * @param[in] ptr is a pointer to the chunk of memory.
  *
  * @retval RTEMS_SUCCESSFUL Successful operation.
  * @retval RTEMS_INVALID_ID The chunk of memory is not a valid chunk in the
  * red-black tree heap.
- * @retval RTEMS_INCORRECT_STATE The chunk of memory is not in the right state.
+ * @retval RTEMS_INCORRECT_STATE The chunk of memory is not in the 
+ * right state.
  */
 rtems_status_code rtems_rbheap_free(rtems_rbheap_control *control, void *ptr);
 
diff --git a/cpukit/sapi/include/rtems/rbtree.h b/cpukit/sapi/include/rtems/rbtree.h
index 4d150deee7..03a55eb992 100644
--- a/cpukit/sapi/include/rtems/rbtree.h
+++ b/cpukit/sapi/include/rtems/rbtree.h
@@ -1,11 +1,12 @@
 /**
- * @file rtems/rbtree.h
- *
- *  This include file contains all the constants and structures associated
- *  with the RBTree API in RTEMS. The rbtree is a Red Black Tree that
- *  is part of the Super Core. This is the published interface to that
- *  code.
- *
+ * @file
+ * 
+ * @brief Constants and Structures Associated with the RBTree API in RTEMS
+ * 
+ * This include file contains all the constants and structures associated
+ * with the RBTree API in RTEMS. The rbtree is a Red Black Tree that
+ * is part of the Super Core. This is the published interface to that
+ * code.
  */
 
 /*
@@ -50,13 +51,13 @@ typedef RBTree_Control rtems_rbtree_control;
 typedef RBTree_Compare_function rtems_rbtree_compare_function;
 
 /**
- *  @brief RBTree initializer for an empty rbtree with designator @a name.
+ * @brief RBTree initializer for an empty rbtree with designator @a name.
  */
 #define RTEMS_RBTREE_INITIALIZER_EMPTY(name) \
   RBTREE_INITIALIZER_EMPTY(name)
 
 /**
- *  @brief RBTree definition for an empty rbtree with designator @a name.
+ * @brief RBTree definition for an empty rbtree with designator @a name.
  */
 #define RTEMS_RBTREE_DEFINE_EMPTY(name) \
   RBTREE_DEFINE_EMPTY(name)
diff --git a/cpukit/sapi/include/rtems/sptables.h b/cpukit/sapi/include/rtems/sptables.h
index d6480acdfe..f32729c7eb 100644
--- a/cpukit/sapi/include/rtems/sptables.h
+++ b/cpukit/sapi/include/rtems/sptables.h
@@ -1,8 +1,10 @@
 /**
- * @file rtems/sptables.h
+ * @file
+ * 
+ * @brief Pre-Initialized Tables Used when in a Single Processor Configuration
  *
- *  This include file contains the executive's pre-initialized tables
- *  used when in a single processor configuration.
+ * This include file contains the executive's pre-initialized tables
+ * used when in a single processor configuration.
  */
 
 /*
diff --git a/cpukit/sapi/include/rtems/timespec.h b/cpukit/sapi/include/rtems/timespec.h
index fcea746445..b67e95c2d3 100644
--- a/cpukit/sapi/include/rtems/timespec.h
+++ b/cpukit/sapi/include/rtems/timespec.h
@@ -26,9 +26,10 @@
  *  @ingroup ClassicRTEMS
  *
  *  @brief Timespec API
+ * 
+ * @{
  *
  */
-/**@{*/
 
 #include <stdbool.h> /* bool */
 #include <stdint.h> /* uint32_t */
@@ -40,11 +41,11 @@ extern "C" {
 
 #include <rtems/timespec.inl>
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif
 
-/**@}*/
-
 #endif
 /* end of include file */