libcsupport: Doxygen enhancement GCI task #4

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

5 files changed, 82 insertions, 10 deletions

diff --git a/cpukit/libcsupport/include/rtems/assoc.h b/cpukit/libcsupport/include/rtems/assoc.h
index 9264560870..496ddb42cd 100644
--- a/cpukit/libcsupport/include/rtems/assoc.h
+++ b/cpukit/libcsupport/include/rtems/assoc.h
@@ -115,6 +115,9 @@ uint32_t     rtems_assoc_local_by_remote_bitfield(
   uint32_t
 );
 
+/**
+ *  @brief RTEMS Associate Pointer by Local
+ */
 const rtems_assoc_t *rtems_assoc_ptr_by_local(
   const rtems_assoc_t *ap,
   uint32_t             local_value
diff --git a/cpukit/libcsupport/include/rtems/error.h b/cpukit/libcsupport/include/rtems/error.h
index ab23ab0ced..056fb8f9c0 100644
--- a/cpukit/libcsupport/include/rtems/error.h
+++ b/cpukit/libcsupport/include/rtems/error.h
@@ -2,6 +2,40 @@
  * @file rtems/error.h
  *
  * Defines and externs for rtems error reporting
+ * 
+ * Currently just used by RTEMS monitor.
+ * 
+ * These routines provide general purpose error reporting.
+ * rtems_error reports an error to stderr and allows use of
+ * printf style formatting.  A newline is appended to all messages.
+ *
+ * error_flag can be specified as any of the following:
+ *
+ *  RTEMS_ERROR_ERRNO       -- include errno text in output
+ *  RTEMS_ERROR_PANIC       -- halts local system after output
+ *  RTEMS_ERROR_ABORT       -- abort after output
+ *
+ * It can also include a rtems_status value which can be OR'd
+ * with the above flags. *
+ *
+ * EXAMPLE
+ *  #include <rtems.h>
+ *  #include <rtems/error.h>
+ *  rtems_error(0, "stray interrupt %d", intr);
+ *
+ * EXAMPLE
+ *        if ((status = rtems_task_create(...)) != RTEMS_SUCCCESSFUL)
+ *        {
+ *            rtems_error(status | RTEMS_ERROR_ABORT,
+ *                        "could not create task");
+ *        }
+ *
+ * EXAMPLE
+ *        if ((fd = open(pathname, O_RDNLY)) < 0)
+ *        {
+ *            rtems_error(RTEMS_ERROR_ERRNO, "open of '%s' failed", pathname);
+ *            goto failed;
+ *        }
  */
 
 
@@ -15,6 +49,15 @@
 extern "C" {
 #endif
 
+/**
+ *  @defgroup ErrorPanicSupport Error And Panic Support
+ *
+ *  @ingroup libcsupport
+ * 
+ *  @brief Defines and externs for rtems error reporting
+ * 
+ */
+
 typedef Internal_errors_t rtems_error_code_t;
 
 /*
@@ -36,11 +79,29 @@ typedef Internal_errors_t rtems_error_code_t;
   (RTEMS_ERROR_ERRNO | RTEMS_ERROR_ABORT | RTEMS_ERROR_PANIC) /* all */
 
 const char *rtems_status_text(rtems_status_code sc);
+
+/**
+ *  @brief Report an Error
+ * 
+ *  @param[in] error_code can be specified as any of the following:
+ *  RTEMS_ERROR_ERRNO       -- include errno text in output
+ *  RTEMS_ERROR_PANIC       -- halts local system after output
+ *  RTEMS_ERROR_ABORT       -- abort after output
+ * 
+ *  @param[in] printf_format is a normal printf(3) format string, 
+ *  with its concommitant arguments
+ *
+ *  @return the number of characters written.
+ */
 int   rtems_error(
   rtems_error_code_t error_code,
   const char *printf_format,
   ...
 );
+
+/**
+ * rtems_panic is shorthand for rtems_error(RTEMS_ERROR_PANIC, ...)
+ */
 void rtems_panic(
   const char *printf_format,
   ...
diff --git a/cpukit/libcsupport/include/rtems/libio_.h b/cpukit/libcsupport/include/rtems/libio_.h
index d6d7ddfca7..19b8661de8 100644
--- a/cpukit/libcsupport/include/rtems/libio_.h
+++ b/cpukit/libcsupport/include/rtems/libio_.h
@@ -194,15 +194,15 @@ void rtems_filesystem_location_clone(
 );
 
 /**
- * @brief Returns the type of a node.
+ *  @brief Returns the Type of a Node
  *
- * This function obtains and releases the file system instance lock.
+ *  This function obtains and releases the file system instance lock.
  *
- * @param[in] loc The location of the node.
+ *  @param[in] loc The location of the node.
  *
- * @return The node type.
+ *  @return The node type.
  *
- * @see rtems_filesystem_instance_lock().
+ *  @see rtems_filesystem_instance_lock().
  */
 rtems_filesystem_node_types_t rtems_filesystem_node_type(
   const rtems_filesystem_location_info_t *loc
@@ -551,6 +551,9 @@ int rtems_filesystem_mknod(
 
 int rtems_filesystem_chdir( rtems_filesystem_location_info_t *loc );
 
+/**
+ *  @brief Change Owner and Group of a File
+ */
 int rtems_filesystem_chown(
   const char *path,
   uid_t owner,
diff --git a/cpukit/libcsupport/include/rtems/malloc.h b/cpukit/libcsupport/include/rtems/malloc.h
index 6b0dfa0e65..fdb57f3bd0 100644
--- a/cpukit/libcsupport/include/rtems/malloc.h
+++ b/cpukit/libcsupport/include/rtems/malloc.h
@@ -88,6 +88,9 @@ typedef void *(*rtems_heap_extend_handler)(
   size_t alloc_size
 );
 
+/**
+ *  @brief RTEMS Extend Heap via Sbrk
+ */
 void *rtems_heap_extend_via_sbrk(
   Heap_Control *heap,
   size_t alloc_size
diff --git a/cpukit/libcsupport/include/rtems/termiostypes.h b/cpukit/libcsupport/include/rtems/termiostypes.h
index 7f2a3eae84..89a997a09e 100644
--- a/cpukit/libcsupport/include/rtems/termiostypes.h
+++ b/cpukit/libcsupport/include/rtems/termiostypes.h
@@ -191,6 +191,9 @@ extern int   rtems_termios_nlinesw;
 /* baudrate xxx integer type */
 typedef uint32_t rtems_termios_baud_t;
 
+/**
+ *  @brief RTEMS Termios Baud Table
+ */
 extern const rtems_assoc_t rtems_termios_baud_table [];
 
 /**
@@ -203,13 +206,12 @@ extern const rtems_assoc_t rtems_termios_baud_table [];
 tcflag_t rtems_termios_number_to_baud(rtems_termios_baud_t baud);
 
 /**
- * @brief Converts the baud part of the Termios control flags @a c_cflag to an
- * integral baud value.
+ *  @brief Convert Baud Part of Termios control flags to an integral Baud Value
  *
- * There is no need to mask the @a c_cflag with @c CBAUD.
+ *  There is no need to mask the @a c_cflag with @c CBAUD.
  *
- * @retval 0 Invalid baud value or a baud value of @c B0.
- * @retval other Integral baud value.
+ *  @retval 0 Invalid baud value or a baud value of @c B0.
+ *  @retval other Integral baud value.
  */
 rtems_termios_baud_t rtems_termios_baud_to_number(tcflag_t c_cflag);