posix: Doxygen enhancement task #4

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

27 files changed, 216 insertions, 33 deletions

diff --git a/cpukit/posix/include/mqueue.h b/cpukit/posix/include/mqueue.h
index 1472983593..56a97a0c7a 100644
--- a/cpukit/posix/include/mqueue.h
+++ b/cpukit/posix/include/mqueue.h
@@ -26,6 +26,13 @@
 #include <rtems/system.h>
 #include <rtems/score/object.h>
 
+/**
+ *  @defgroup POSIX_MQUEUE Message Queues
+ *
+ *  @ingroup POSIX
+ */
+/**@{*/
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -72,7 +79,21 @@ int mq_close(
 );
 
 /**
+ *  @brief Remove a Message Queue
+ *
  *  15.2.2 Remove a Message Queue, P1003.1b-1993, p. 276
+ *
+ *  NOTE:  The structure of the routines is identical to that of POSIX
+ *         Message_queues to leave the option of having unnamed message
+ *         queues at a future date.  They are currently not part of the
+ *         POSIX standard but unnamed message_queues are.  This is also
+ *         the reason for the apparently unnecessary tracking of
+ *         the process_shared attribute.  [In addition to the fact that
+ *         it would be trivial to add pshared to the mq_attr structure
+ *         and have process private message queues.]
+ *
+ *         This code ignores the O_RDONLY/O_WRONLY/O_RDWR flag at open
+ *         time.
  */
 int mq_unlink(
   const char *name
@@ -167,6 +188,6 @@ int mq_getattr(
 #endif
 
 #endif /* _POSIX_MESSAGE_PASSING */
-
+/**@}*/
 #endif
 /* end of include file */
diff --git a/cpukit/posix/include/rtems/posix/cond.h b/cpukit/posix/include/rtems/posix/cond.h
index 4b22dff942..b089abe4a9 100644
--- a/cpukit/posix/include/rtems/posix/cond.h
+++ b/cpukit/posix/include/rtems/posix/cond.h
@@ -17,6 +17,12 @@
 #ifndef _RTEMS_POSIX_COND_H
 #define _RTEMS_POSIX_COND_H
 
+/**
+ *  @defgroup POSIX_COND_VARS Condition Variables
+ *
+ *  @ingroup POSIX
+ */
+/**@{*/
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -56,6 +62,8 @@ POSIX_EXTERN Objects_Information  _POSIX_Condition_variables_Information;
 extern const pthread_condattr_t _POSIX_Condition_variables_Default_attributes;
 
 /*
+ * @brief Initialization Necessary for this Manager
+ *
  *  _POSIX_Condition_variables_Manager_initialization
  *
  *  DESCRIPTION:
@@ -125,6 +133,8 @@ RTEMS_INLINE_ROUTINE bool _POSIX_Condition_variables_Is_null (
 );
 
 /*
+ * @brief Implements wake up version of the "signal" operation
+ *
  *  _POSIX_Condition_variables_Signal_support
  *
  *  DESCRIPTION:
@@ -174,6 +184,6 @@ POSIX_Condition_variables_Control *_POSIX_Condition_variables_Get (
 #ifdef __cplusplus
 }
 #endif
-
+/**@}*/
 #endif
 /*  end of include file */
diff --git a/cpukit/posix/include/rtems/posix/key.h b/cpukit/posix/include/rtems/posix/key.h
index e056d8d89a..ce4f093b13 100644
--- a/cpukit/posix/include/rtems/posix/key.h
+++ b/cpukit/posix/include/rtems/posix/key.h
@@ -19,6 +19,12 @@
 
 #include <rtems/score/object.h>
 
+/**
+ *  @defgroup POSIX_KEY Key
+ *
+ *  @ingroup POSIX
+ */
+/**@{*/
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -45,7 +51,7 @@ typedef struct {
 POSIX_EXTERN Objects_Information  _POSIX_Keys_Information;
 
 /**
- *  @brief _POSIX_Keys_Manager_initialization
+ *  @brief POSIX Keys Manager Initialization
  *
  *  This routine performs the initialization necessary for this manager.
  */
@@ -95,6 +101,6 @@ RTEMS_INLINE_ROUTINE void _POSIX_Keys_Free (
 #ifdef __cplusplus
 }
 #endif
-
+/**@}*/
 #endif
 /*  end of include file */
diff --git a/cpukit/posix/include/rtems/posix/ptimer.h b/cpukit/posix/include/rtems/posix/ptimer.h
index 046a7af477..a7c083711a 100644
--- a/cpukit/posix/include/rtems/posix/ptimer.h
+++ b/cpukit/posix/include/rtems/posix/ptimer.h
@@ -20,6 +20,12 @@
 #ifndef _RTEMS_POSIX_PTIMER_H
 #define _RTEMS_POSIX_PTIMER_H
 
+/**
+ *  @defgroup POSIX_PRIV_TIMERS Timers
+ *
+ *  @ingroup POSIX
+ */
+/**@{*/
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -37,6 +43,8 @@ extern "C" {
 void _POSIX_Timer_Manager_initialization(void);
 
 /*
+ *  @brief Create a Per-Process Timer
+ *
  *  14.2.2 Create a Per-Process Timer, P1003.1b-1993, p. 264
  *
  *  timer_create
@@ -90,5 +98,5 @@ int timer_gettime(
 int timer_getoverrun(
   timer_t   timerid
 );
-
+/**@}*/
 #endif
diff --git a/cpukit/posix/include/rtems/posix/threadsup.h b/cpukit/posix/include/rtems/posix/threadsup.h
index 82f82b40c3..c5a2e3db7e 100644
--- a/cpukit/posix/include/rtems/posix/threadsup.h
+++ b/cpukit/posix/include/rtems/posix/threadsup.h
@@ -20,6 +20,12 @@
 #include <rtems/score/coresem.h>
 #include <rtems/score/tqdata.h>
 
+/**
+ *  @defgroup POSIX_THREAD Thread API Extension
+ *
+ *  @ingroup POSIX
+ */
+/**@{*/
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -75,12 +81,17 @@ typedef struct {
 /*!
  *  @brief POSIX Thread Exit Shared Helper
  *
+ *  16.1.5.1 Thread Termination, p1003.1c/Draft 10, p. 150
+ *
  *  This method is a helper routine which ensures that all
  *  POSIX thread calls which result in a thread exiting will
  *  do so in the same manner.
  *
  *  @param[in] the_thread is the thread exiting or being canceled
  *  @param[in] value_ptr is the value to be returned by the thread
+ *
+ *  NOTE: Key destructors are executed in the POSIX api delete extension.
+ *
  */
 void _POSIX_Thread_Exit(
   Thread_Control *the_thread,
@@ -90,6 +101,6 @@ void _POSIX_Thread_Exit(
 #ifdef __cplusplus
 }
 #endif
-
+/**@}*/
 #endif
 /* end of include file */
diff --git a/cpukit/posix/include/rtems/posix/time.h b/cpukit/posix/include/rtems/posix/time.h
index 104997fcf8..d0dc4a27fe 100644
--- a/cpukit/posix/include/rtems/posix/time.h
+++ b/cpukit/posix/include/rtems/posix/time.h
@@ -19,6 +19,12 @@
 
 #include <rtems/score/timespec.h>
 #include <rtems/score/watchdog.h>
+/**
+ *  @defgroup POSIX_TIMETYPES Time Types
+ *
+ *  @ingroup POSIX
+ */
+/**@{*/
 
 /**
  *  @brief Absolute Timeout Conversion Results
@@ -59,3 +65,4 @@ POSIX_Absolute_timeout_conversion_results_t _POSIX_Absolute_timeout_to_ticks(
 );
 
 #endif
+/**@}*/
diff --git a/cpukit/posix/include/rtems/posix/timer.h b/cpukit/posix/include/rtems/posix/timer.h
index d193a88b87..1298178e95 100644
--- a/cpukit/posix/include/rtems/posix/timer.h
+++ b/cpukit/posix/include/rtems/posix/timer.h
@@ -21,6 +21,12 @@
 #include <rtems/score/object.h>
 #include <rtems/score/watchdog.h> /* Watchdog_Control */
 
+/**
+ *  @defgroup POSIX_INTERNAL_TIMERS Timers
+ *
+ *  @ingroup POSIX
+ */
+/**@{*/
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -75,6 +81,8 @@ typedef struct {
 void _POSIX_Timer_Manager_initialization(void);
 
 /*
+ *  @brief Operation that is run when a timer expires
+ *
  *  Timer TSR
  */
 void _POSIX_Timer_TSR(Objects_Id timer, void *data);
@@ -103,6 +111,6 @@ POSIX_EXTERN Objects_Information  _POSIX_Timer_Information;
 #ifdef __cplusplus
 }
 #endif
-
+/**@}*/
 #endif
 /* end of include file */
diff --git a/cpukit/posix/src/barrierattrgetpshared.c b/cpukit/posix/src/barrierattrgetpshared.c
index 837c050ef5..1141fa5a5c 100644
--- a/cpukit/posix/src/barrierattrgetpshared.c
+++ b/cpukit/posix/src/barrierattrgetpshared.c
@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief Barrier Attributes Get Process Shared
+ * @ingroup POSIX
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/posix/src/cleanuppush.c b/cpukit/posix/src/cleanuppush.c
index 23f022e1d1..87df540555 100644
--- a/cpukit/posix/src/cleanuppush.c
+++ b/cpukit/posix/src/cleanuppush.c
@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief Establishing Cancellation Handlers
+ * @ingroup POSIX
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/posix/src/clocksettime.c b/cpukit/posix/src/clocksettime.c
index de2c20de50..7e7edb4f56 100644
--- a/cpukit/posix/src/clocksettime.c
+++ b/cpukit/posix/src/clocksettime.c
@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief Set Time of Clock
+ * @ingroup POSIX
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/posix/src/cond.c b/cpukit/posix/src/cond.c
index b66509f8da..d2f3b81618 100644
--- a/cpukit/posix/src/cond.c
+++ b/cpukit/posix/src/cond.c
@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief Initialization Necessary for this Manager
+ * @ingroup POSIX_COND_VARS Condition Variables
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/posix/src/condsignalsupp.c b/cpukit/posix/src/condsignalsupp.c
index 5ab6e9de95..36bb60ebb2 100644
--- a/cpukit/posix/src/condsignalsupp.c
+++ b/cpukit/posix/src/condsignalsupp.c
@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief Implements wake up version of the "signal" operation
+ * @ingroup POSIX_COND_VARS Condition Variables
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/posix/src/condtimedwait.c b/cpukit/posix/src/condtimedwait.c
index 2789e210c1..031376cfea 100644
--- a/cpukit/posix/src/condtimedwait.c
+++ b/cpukit/posix/src/condtimedwait.c
@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief Waiting on a Condition
+ * @ingroup POSIX
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/posix/src/key.c b/cpukit/posix/src/key.c
index ee8b496b2f..6eace26eed 100644
--- a/cpukit/posix/src/key.c
+++ b/cpukit/posix/src/key.c
@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief POSIX Keys Manager Initialization
+ * @ingroup POSIX_KEY Key
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/posix/src/mprotect.c b/cpukit/posix/src/mprotect.c
index 9d3c0eb09a..32de472a21 100644
--- a/cpukit/posix/src/mprotect.c
+++ b/cpukit/posix/src/mprotect.c
@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief Change Memory Protection
+ * @ingroup POSIX
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/posix/src/mqueueunlink.c b/cpukit/posix/src/mqueueunlink.c
index 8e48ffe669..0f68ae727a 100644
--- a/cpukit/posix/src/mqueueunlink.c
+++ b/cpukit/posix/src/mqueueunlink.c
@@ -1,16 +1,11 @@
-/*
- *  NOTE:  The structure of the routines is identical to that of POSIX
- *         Message_queues to leave the option of having unnamed message
- *         queues at a future date.  They are currently not part of the
- *         POSIX standard but unnamed message_queues are.  This is also
- *         the reason for the apparently unnecessary tracking of
- *         the process_shared attribute.  [In addition to the fact that
- *         it would be trivial to add pshared to the mq_attr structure
- *         and have process private message queues.]
- *
- *         This code ignores the O_RDONLY/O_WRONLY/O_RDWR flag at open
- *         time.
+/**
+ * @file
  *
+ * @brief Remove a Message Queue
+ * @ingroup POSIX_MQUEUE Message Queues
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/posix/src/mutexattrgetprioceiling.c b/cpukit/posix/src/mutexattrgetprioceiling.c
index a571ad5ba2..949fd3b32c 100644
--- a/cpukit/posix/src/mutexattrgetprioceiling.c
+++ b/cpukit/posix/src/mutexattrgetprioceiling.c
@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief Mutex Initialization Scheduling Attributes
+ * @ingroup POSIX
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/posix/src/posixtimespecabsolutetimeout.c b/cpukit/posix/src/posixtimespecabsolutetimeout.c
index 24362c5aa3..e94805e692 100644
--- a/cpukit/posix/src/posixtimespecabsolutetimeout.c
+++ b/cpukit/posix/src/posixtimespecabsolutetimeout.c
@@ -1,5 +1,8 @@
-/*
- *  Convert abstime timeout to ticks
+/**
+ * @file
+ *
+ * @brief Convert Absolute Timeout to Ticks
+ * @ingroup POSIX_TIMETYPES Time Types
  */
 
 /*
diff --git a/cpukit/posix/src/prwlocktrywrlock.c b/cpukit/posix/src/prwlocktrywrlock.c
index 06a3cbb2e5..f8857a831b 100644
--- a/cpukit/posix/src/prwlocktrywrlock.c
+++ b/cpukit/posix/src/prwlocktrywrlock.c
@@ -1,6 +1,11 @@
-/*
- *  POSIX RWLock Manager -- Attempt to Obtain a Write Lock on a RWLock Instance
+/**
+ * @file
  *
+ * @brief Attempt to Obtain a Write Lock on a RWLock Instance
+ * @ingroup POSIX
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/posix/src/pspintrylock.c b/cpukit/posix/src/pspintrylock.c
index e3f2659735..de89b4e579 100644
--- a/cpukit/posix/src/pspintrylock.c
+++ b/cpukit/posix/src/pspintrylock.c
@@ -1,6 +1,11 @@
-/*
- *  POSIX Spinlock Manager -- Wait at a Spinlock
+/**
+ * @file
  *
+ * @brief Wait at a Spinlock
+ * @ingroup POSIX
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/posix/src/pthreadexit.c b/cpukit/posix/src/pthreadexit.c
index e89ed855c3..2e995c49bc 100644
--- a/cpukit/posix/src/pthreadexit.c
+++ b/cpukit/posix/src/pthreadexit.c
@@ -1,8 +1,11 @@
-/*
- *  16.1.5.1 Thread Termination, p1003.1c/Draft 10, p. 150
- *
- *  NOTE: Key destructors are executed in the POSIX api delete extension.
+/**
+ * @file
  *
+ * @brief POSIX Thread Exit Shared Helper
+ * @ingroup POSIX_THREAD Thread API Extension
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2011.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/posix/src/setcancelstate.c b/cpukit/posix/src/setcancelstate.c
index a5356aa945..31bef65eff 100644
--- a/cpukit/posix/src/setcancelstate.c
+++ b/cpukit/posix/src/setcancelstate.c
@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief Setting Cancelability State
+ * @ingroup POSIX
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2009.
  *  On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/posix/src/sigemptyset.c b/cpukit/posix/src/sigemptyset.c
index 245639e896..5cfc310ba1 100644
--- a/cpukit/posix/src/sigemptyset.c
+++ b/cpukit/posix/src/sigemptyset.c
@@ -1,6 +1,11 @@
-/*
- *  3.3.3 Manipulate Signal Sets, P1003.1b-1993, p. 69
+/**
+ * @file
  *
+ * @brief Manipulate Signal Sets
+ * @ingroup POSIX
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/posix/src/sigpending.c b/cpukit/posix/src/sigpending.c
index 9145c988e4..c62d878b6b 100644
--- a/cpukit/posix/src/sigpending.c
+++ b/cpukit/posix/src/sigpending.c
@@ -1,6 +1,11 @@
-/*
- *  3.3.6 Examine Pending Signals, P1003.1b-1993, p. 75
+/**
+ * @file
  *
+ * @brief Examine Pending Signals
+ * @ingroup POSIX
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/posix/src/sysconf.c b/cpukit/posix/src/sysconf.c
index e6c73de2ec..fb0939fbe2 100644
--- a/cpukit/posix/src/sysconf.c
+++ b/cpukit/posix/src/sysconf.c
@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief Get Configurable System Variables
+ * @ingroup POSIX
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/posix/src/timercreate.c b/cpukit/posix/src/timercreate.c
index 6dfa75b9c8..bd52f87fe9 100644
--- a/cpukit/posix/src/timercreate.c
+++ b/cpukit/posix/src/timercreate.c
@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief Create a Per-Process Timer
+ * @ingroup POSIX_PRIV_TIMERS Timers
+ */
+
 /*
  *  14.2.2 Create a Per-Process Timer, P1003.1b-1993, p. 264
  *
diff --git a/cpukit/posix/src/timertsr.c b/cpukit/posix/src/timertsr.c
index 0ef40ffdfe..ad17ae91c2 100644
--- a/cpukit/posix/src/timertsr.c
+++ b/cpukit/posix/src/timertsr.c
@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief Operation that is run when a timer expires
+ * @ingroup POSIX_INTERNAL_TIMERS Timers
+ */
+
 /*
  * _POSIX_Timer_TSR
  *