sapi misc: Clean up Doxygen GCI task #1

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

4 files changed, 114 insertions, 17 deletions

diff --git a/cpukit/sapi/include/rtems/extension.h b/cpukit/sapi/include/rtems/extension.h
index f9f1ae1381..3d54092a8c 100644
--- a/cpukit/sapi/include/rtems/extension.h
+++ b/cpukit/sapi/include/rtems/extension.h
@@ -38,6 +38,11 @@ typedef struct {
   User_extensions_Control  Extension;
 }   Extension_Control;
 
+/**
+ *  @brief Initialize Extension Manager
+ *
+ *  This routine initializes all extension manager related data structures.
+ */
 void _Extension_Manager_initialization(void);
 
 typedef User_extensions_routine
diff --git a/cpukit/sapi/include/rtems/fatal.h b/cpukit/sapi/include/rtems/fatal.h
index 64344b36b8..7b7c5b1925 100644
--- a/cpukit/sapi/include/rtems/fatal.h
+++ b/cpukit/sapi/include/rtems/fatal.h
@@ -57,9 +57,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 +68,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,7 +81,7 @@ void rtems_fatal(
 /**
  * @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.
diff --git a/cpukit/sapi/include/rtems/init.h b/cpukit/sapi/include/rtems/init.h
index 95b7cc79e6..8b5fab91fd 100644
--- a/cpukit/sapi/include/rtems/init.h
+++ b/cpukit/sapi/include/rtems/init.h
@@ -87,7 +87,7 @@ void rtems_initialize_start_multitasking(void)
   RTEMS_COMPILER_NO_RETURN_ATTRIBUTE;
 
 /**
- *  @brief rtems_shutdown_executive
+ *  @brief Shutdown the RTEMS environment
  *
  *  This routine implements the rtems_shutdown_executive directive.  The
  *  invocation of this directive results in the RTEMS environment being
diff --git a/cpukit/sapi/include/rtems/io.h b/cpukit/sapi/include/rtems/io.h
index 5477860b5a..627b53581c 100644
--- a/cpukit/sapi/include/rtems/io.h
+++ b/cpukit/sapi/include/rtems/io.h
@@ -100,11 +100,13 @@ rtems_status_code rtems_io_register_driver(
 );
 
 /**
- * @brief Unregisters the device driver with number @a major.
+ *  @brief Unregister a Driver from the Device Driver Table.
  *
- * @retval RTEMS_SUCCESSFUL Device driver successfully unregistered.
- * @retval RTEMS_UNSATISFIED Invalid major number.
- * @retval RTEMS_CALLED_FROM_ISR Called from interrupt context.
+ *  @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.
  */
 rtems_status_code rtems_io_unregister_driver(
   rtems_device_major_number major
@@ -126,41 +128,101 @@ rtems_status_code rtems_io_register_name(
 /** @} */
 
 /**
- * @name Device Driver Invocation
+ *  @brief IO Driver Initialization
  *
- * @{
+ *  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)
+ *
+ *  @return status code
  */
-
 rtems_status_code rtems_io_initialize(
   rtems_device_major_number  major,
   rtems_device_minor_number  minor,
   void                      *argument
 );
 
+/**
+ *  @brief Opening for The IO Manager
+ *  
+ *  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).
+ *
+ *  @return Status code.
+ */
 rtems_status_code rtems_io_open(
   rtems_device_major_number  major,
   rtems_device_minor_number  minor,
   void                      *argument
 );
 
+/**
+ *  @brief Closing for 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).
+ *
+ *  @return Status code.
+ */
 rtems_status_code rtems_io_close(
   rtems_device_major_number  major,
   rtems_device_minor_number  minor,
   void                      *argument
 );
 
+/**
+ *  @brief Reading for 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).
+ *
+ *  @return Status code.
+ */
 rtems_status_code rtems_io_read(
   rtems_device_major_number  major,
   rtems_device_minor_number  minor,
   void                      *argument
 );
 
+/**
+ *  @brief Writing for 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).
+ *
+ *  @return Status code.
+ */
 rtems_status_code rtems_io_write(
   rtems_device_major_number  major,
   rtems_device_minor_number  minor,
   void                      *argument
 );
 
+/**
+ *  @brief Control for 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).
+ *
+ *  @return Status code.
+ */
 rtems_status_code rtems_io_control(
   rtems_device_major_number  major,
   rtems_device_minor_number  minor,
@@ -190,8 +252,20 @@ 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
+ *
+ *  @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
+ *
+ *  Initializes all device drivers.
+ */
 void _IO_Initialize_all_drivers( void );
 
 #ifdef __cplusplus
@@ -199,4 +273,26 @@ void _IO_Initialize_all_drivers( void );
 #endif
 
 #endif
-/* end of include file */
+  rtems_io_write(
+  rtems_device_major_number  major,
+  rtems_device_minor_number  minor,
+  void                      *argument
+);
+
+/**
+ *  @brief Control for 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).
+ *
+ *  @return Status code.
+ */
+rtems_status_code rtems_io_control(
+  rtems_device_major_number  major,
+  rtems_device_minor_number  minor,
+  void                      *argument
+);
+