posix: Doxygen Enhancement Task #1

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

20 files changed, 171 insertions, 133 deletions

diff --git a/cpukit/posix/src/adjtime.c b/cpukit/posix/src/adjtime.c
index db88c923e1..23f7d3a9ed 100644
--- a/cpukit/posix/src/adjtime.c
+++ b/cpukit/posix/src/adjtime.c
@@ -1,9 +1,8 @@
-/*
- *  adjime() function
+/**
+ *  @file
  *
- *  This method was initially added as part of porting NTP to RTEMS.
- *  It is a BSD compatability function and now is available on
- *  GNU/Linux.
+ *  @brief Correct the Time to Synchronize the System Clock
+ *  @ingroup POSIX
  */
 
 /*
@@ -31,12 +30,15 @@
 #include <rtems/score/thread.h>
 #include <rtems/score/timespec.h>
 
-/*
+/**
+ * This method was initially added as part of porting NTP to RTEMS.
+ *  It is a BSD compatability function and now is available on
+ *  GNU/Linux.
+ * 
  *  At one point there was a static variable named adjustment
  *  used by this implementation.  I don't see any reason for it
  *  to be here based upon the GNU/Linux documentation.
  */
-
 int  adjtime(
   const struct timeval *delta,
   struct timeval *olddelta
diff --git a/cpukit/posix/src/condattrgetpshared.c b/cpukit/posix/src/condattrgetpshared.c
index a35f85e414..298c2618b3 100644
--- a/cpukit/posix/src/condattrgetpshared.c
+++ b/cpukit/posix/src/condattrgetpshared.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Get the Process-Shared Condition Variable Attributes
+ *  @ingroup POSIX
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
@@ -22,11 +29,10 @@
 #include <rtems/posix/time.h>
 #include <rtems/posix/mutex.h>
 
-/*
+/**
  *  11.4.1 Condition Variable Initialization Attributes,
  *            P1003.1c/Draft 10, p. 96
  */
-
 int pthread_condattr_getpshared(
   const pthread_condattr_t *attr,
   int                      *pshared
diff --git a/cpukit/posix/src/conddestroy.c b/cpukit/posix/src/conddestroy.c
index 905fb1ecca..0f32b89da3 100644
--- a/cpukit/posix/src/conddestroy.c
+++ b/cpukit/posix/src/conddestroy.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Destroy a Condition Variable
+ *  @ingroup POSIX
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
@@ -22,11 +29,10 @@
 #include <rtems/posix/time.h>
 #include <rtems/posix/mutex.h>
 
-/*
+/**
  *  11.4.2 Initializing and Destroying a Condition Variable,
  *         P1003.1c/Draft 10, p. 87
  */
-
 int pthread_cond_destroy(
   pthread_cond_t           *cond
 )
diff --git a/cpukit/posix/src/condsignal.c b/cpukit/posix/src/condsignal.c
index 8b5c2c90c4..debc110143 100644
--- a/cpukit/posix/src/condsignal.c
+++ b/cpukit/posix/src/condsignal.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Signal a Condition 
+ *  @ingroup POSIX
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
@@ -22,10 +29,9 @@
 #include <rtems/posix/time.h>
 #include <rtems/posix/mutex.h>
 
-/*
+/**
  *  11.4.3 Broadcasting and Signaling a Condition, P1003.1c/Draft 10, p. 101
  */
-
 int pthread_cond_signal(
   pthread_cond_t   *cond
 )
diff --git a/cpukit/posix/src/execve.c b/cpukit/posix/src/execve.c
index c6f6ede19b..03320e52a0 100644
--- a/cpukit/posix/src/execve.c
+++ b/cpukit/posix/src/execve.c
@@ -1,6 +1,11 @@
-/*
- *  execve() - POSIX 1003.1b 3.1.2
+/**
+ *  @file
  *
+ *  @brief Execute a Program
+ *  @ingroup POSIX
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -18,6 +23,9 @@
 #include <errno.h>
 #include <rtems/seterr.h>
 
+/**
+ *  POSIX 1003.1b 3.1.2
+ */
 int execve(
   const char *path,
   char *const argv[],
diff --git a/cpukit/posix/src/keycreate.c b/cpukit/posix/src/keycreate.c
index 493b6fb278..3ac462dbcb 100644
--- a/cpukit/posix/src/keycreate.c
+++ b/cpukit/posix/src/keycreate.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Thread-Specific Data Key Create
+ *  @ingroup POSIX
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2010.
  *  On-Line Applications Research Corporation (OAR).
@@ -21,10 +28,9 @@
 #include <rtems/score/wkspace.h>
 #include <rtems/posix/key.h>
 
-/*
+/**
  *  17.1.1 Thread-Specific Data Key Create, P1003.1c/Draft 10, p. 163
  */
-
 int pthread_key_create(
   pthread_key_t  *key,
   void          (*destructor)( void * )
diff --git a/cpukit/posix/src/mqueuereceive.c b/cpukit/posix/src/mqueuereceive.c
index 44defc250f..c5f9257747 100644
--- a/cpukit/posix/src/mqueuereceive.c
+++ b/cpukit/posix/src/mqueuereceive.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 Receive a Message From a Message Queue 
+ *  @ingroup POSIX_MQUEUE
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -37,12 +32,6 @@
 #include <rtems/posix/mqueue.h>
 #include <rtems/posix/time.h>
 
-/*
- *  15.2.5 Receive a Message From a Message Queue, P1003.1b-1993, p. 279
- *
- *  NOTE: P1003.4b/D8, p. 45 adds mq_timedreceive().
- */
-
 ssize_t mq_receive(
   mqd_t         mqdes,
   char         *msg_ptr,
diff --git a/cpukit/posix/src/mqueuetimedsend.c b/cpukit/posix/src/mqueuetimedsend.c
index f06197fa79..da7e0e1058 100644
--- a/cpukit/posix/src/mqueuetimedsend.c
+++ b/cpukit/posix/src/mqueuetimedsend.c
@@ -1,15 +1,8 @@
-/*
- *  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.]
+/**
+ *  @file
  *
- *         This code ignores the O_RDONLY/O_WRONLY/O_RDWR flag at open
- *         time.
+ *  @brief Send a Message to a Message Queue
+ *  @ingroup POSIX_MQUEUE
  */
 
 /*
@@ -39,12 +32,6 @@
 #include <rtems/posix/mqueue.h>
 #include <rtems/posix/time.h>
 
-/*
- *  15.2.4 Send a Message to a Message Queue, P1003.1b-1993, p. 277
- *
- *  NOTE: P1003.4b/D8, p. 45 adds mq_timedsend().
- */
-
 int mq_timedsend(
   mqd_t                  mqdes,
   const char            *msg_ptr,
diff --git a/cpukit/posix/src/mutexattrsettype.c b/cpukit/posix/src/mutexattrsettype.c
index a005747718..861e616ad3 100644
--- a/cpukit/posix/src/mutexattrsettype.c
+++ b/cpukit/posix/src/mutexattrsettype.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Set a Mutex Type
+ *  @ingroup POSIX
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2009.
  *  On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/posix/src/mutextranslatereturncode.c b/cpukit/posix/src/mutextranslatereturncode.c
index 53b5b0ee00..8c2d9af8ce 100644
--- a/cpukit/posix/src/mutextranslatereturncode.c
+++ b/cpukit/posix/src/mutextranslatereturncode.c
@@ -1,6 +1,11 @@
-/*
- *  POSIX Mutex Error Translation
+/**
+ *  @file
  *
+ *  @brief POSIX Mutex Translate Core Mutex Return Code
+ *  @ingroup POSIX_MUTEX
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -20,17 +25,6 @@
 #include <rtems/score/coremutex.h>
 #include <rtems/posix/mutex.h>
 
-/*
- *  _POSIX_Mutex_Translate_core_mutex_return_code
- *
- *  Input parameters:
- *    the_mutex_status - mutex status code to translate
- *
- *  Output parameters:
- *    status code - translated POSIX status code
- *
- */
-
 static int _POSIX_Mutex_Return_codes[CORE_MUTEX_STATUS_LAST + 1] = {
   0,                      /* CORE_MUTEX_STATUS_SUCCESSFUL */
   EBUSY,                  /* CORE_MUTEX_STATUS_UNSATISFIED_NOWAIT */
diff --git a/cpukit/posix/src/prwlockdestroy.c b/cpukit/posix/src/prwlockdestroy.c
index 684e173e18..9b644ba943 100644
--- a/cpukit/posix/src/prwlockdestroy.c
+++ b/cpukit/posix/src/prwlockdestroy.c
@@ -1,6 +1,10 @@
-/*
- *  POSIX RWLock Manager -- Destroy a RWLock
+/**
+ *  @file
  *
+ *  @brief Destroy a RWLock
+ *  @ingroup POSIX
+ */
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -19,21 +23,17 @@
 #include <rtems/system.h>
 #include <rtems/posix/rwlock.h>
 
-/*
- *  pthread_rwlock_destroy
- *
+/**
  *  This directive allows a thread to delete a rwlock specified by
  *  the rwlock id.  The rwlock is freed back to the inactive
  *  rwlock chain.
  *
- *  Input parameters:
- *    rwlock - rwlock id
+ *  @param[in] rwlock is the rwlock id
  *
- *  Output parameters:
- *    0           - if successful
- *    error code  - if unsuccessful
+ *  @return This method returns 0 if there was not an
+ *  error. Otherwise, a status code is returned indicating the
+ *  source of the error.
  */
-
 int pthread_rwlock_destroy(
   pthread_rwlock_t *rwlock
 )
diff --git a/cpukit/posix/src/prwlocktranslatereturncode.c b/cpukit/posix/src/prwlocktranslatereturncode.c
index 3c75e10aa4..48be176d36 100644
--- a/cpukit/posix/src/prwlocktranslatereturncode.c
+++ b/cpukit/posix/src/prwlocktranslatereturncode.c
@@ -1,6 +1,11 @@
-/*
- *  RWLock Manager -- Translate SuperCore Status
+/**
+ *  @file
  *
+ *  @brief POSIX RWLock Translate Core RWLock Return Code
+ *  @ingroup POSIX_RWLOCK
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -19,17 +24,6 @@
 #include <rtems/system.h>
 #include <rtems/posix/rwlock.h>
 
-/*
- *  _POSIX_RWLock_Translate_core_rwlock_return_code
- *
- *  Input parameters:
- *    the_rwlock_status - rwlock status code to translate
- *
- *  Output parameters:
- *    status code - translated POSIX status code
- *
- */
-
 static int _POSIX_RWLock_Return_codes[CORE_RWLOCK_STATUS_LAST + 1] = {
   0,                        /* CORE_RWLOCK_SUCCESSFUL */
   EINVAL,                   /* CORE_RWLOCK_DELETED */
diff --git a/cpukit/posix/src/psignalchecksignal.c b/cpukit/posix/src/psignalchecksignal.c
index 171d7c8121..57237d3055 100644
--- a/cpukit/posix/src/psignalchecksignal.c
+++ b/cpukit/posix/src/psignalchecksignal.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief POSIX Signals Check Signal
+ *  @ingroup POSIX_SIGNALS
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
@@ -31,11 +38,6 @@
 #include <rtems/posix/time.h>
 #include <stdio.h>
 
-
-/*
- *  _POSIX_signals_Check_signal
- */
-
 bool    _POSIX_signals_Check_signal(
   POSIX_API_Control  *api,
   int                 signo,
diff --git a/cpukit/posix/src/pspinlock.c b/cpukit/posix/src/pspinlock.c
index ce1a2bb3c5..7f6793c1d5 100644
--- a/cpukit/posix/src/pspinlock.c
+++ b/cpukit/posix/src/pspinlock.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).
  *
@@ -19,19 +24,15 @@
 #include <rtems/system.h>
 #include <rtems/posix/spinlock.h>
 
-/*
- *  pthread_spin_lock
- *
+/**
  *  This directive allows a thread to wait at a spinlock.
  *
- *  Input parameters:
- *    spinlock    - spinlock id
- *
- *  Output parameters:
- *    0          - if successful
- *    error code - if unsuccessful
+ *  @param[in] spinlock is spinlock id
+ * 
+ *  @return This method returns 0 if there was not an
+ *  error. Otherwise, a status code is returned indicating the
+ *  source of the error.
  */
-
 int pthread_spin_lock(
   pthread_spinlock_t *spinlock
 )
diff --git a/cpukit/posix/src/psxpriorityisvalid.c b/cpukit/posix/src/psxpriorityisvalid.c
index 3ef7a1ec26..eda424e420 100644
--- a/cpukit/posix/src/psxpriorityisvalid.c
+++ b/cpukit/posix/src/psxpriorityisvalid.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief POSIX Is Priority Valid
+ *  @ingroup POSIX_PRIORITY
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/posix/src/pthreadatfork.c b/cpukit/posix/src/pthreadatfork.c
index 767f113d0c..558bc77555 100644
--- a/cpukit/posix/src/pthreadatfork.c
+++ b/cpukit/posix/src/pthreadatfork.c
@@ -1,15 +1,11 @@
-/*
- *  pthread_atfork() - POSIX 1003.1b 3.1.3
- *
- *  3.1.3 Register Fork Handlers, P1003.1c/Draft 10, P1003.1c/Draft 10, p. 27
- *
- *  RTEMS does not support processes, so we fall under this and do not
- *  provide this routine:
- *
- *  "Either the implementation shall support the pthread_atfork() function
- *   as described above or the pthread_atfork() funciton shall not be
- *   provided."
+/**
+ *  @file
  *
+ *  @brief Register Fork Handlers
+ *  @ingroup POSIX
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -27,6 +23,18 @@
 #include <errno.h>
 #include <rtems/seterr.h>
 
+/**
+ *  POSIX 1003.1b 3.1.3
+ *
+ *  3.1.3 Register Fork Handlers, P1003.1c/Draft 10, P1003.1c/Draft 10, p. 27
+ *
+ *  RTEMS does not support processes, so we fall under this and do not
+ *  provide this routine:
+ *
+ *  "Either the implementation shall support the pthread_atfork() function
+ *   as described above or the pthread_atfork() funciton shall not be
+ *   provided."
+ */
 int pthread_atfork(
   void (*prepare)(void) __attribute__((unused)),
   void (*parent)(void) __attribute__((unused)),
diff --git a/cpukit/posix/src/pthreadattrgetschedpolicy.c b/cpukit/posix/src/pthreadattrgetschedpolicy.c
index 1a79711fb2..6b57e8a2ca 100644
--- a/cpukit/posix/src/pthreadattrgetschedpolicy.c
+++ b/cpukit/posix/src/pthreadattrgetschedpolicy.c
@@ -1,6 +1,11 @@
-/*
- *  13.5.1 Thread Creation Scheduling Parameters, P1003.1c/Draft 10, p. 120
+/**
+ *  @file
  *
+ *  @brief Get The Schedpolicy Attribute
+ *  @ingroup POSIX
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -16,6 +21,9 @@
 #include <pthread.h>
 #include <errno.h>
 
+/**
+ *  13.5.1 Thread Creation Scheduling Parameters, P1003.1c/Draft 10, p. 120
+ */
 int pthread_attr_getschedpolicy(
   const pthread_attr_t  *attr,
   int                   *policy
diff --git a/cpukit/posix/src/semdestroy.c b/cpukit/posix/src/semdestroy.c
index b2a03f5ff7..14ba520fa3 100644
--- a/cpukit/posix/src/semdestroy.c
+++ b/cpukit/posix/src/semdestroy.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Destroy an Unnamed Semaphore
+ *  @ingroup POSIX_SEMAPHORE
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
@@ -25,10 +32,6 @@
 #include <rtems/posix/time.h>
 #include <rtems/seterr.h>
 
-/*
- *  11.2.2 Destroy an Unnamed Semaphore, P1003.1b-1993, p.220
- */
-
 int sem_destroy(
   sem_t *sem
 )
diff --git a/cpukit/posix/src/sempost.c b/cpukit/posix/src/sempost.c
index e1d6221ad7..7ce367986f 100644
--- a/cpukit/posix/src/sempost.c
+++ b/cpukit/posix/src/sempost.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Unlock a Semaphore
+ *  @ingroup POSIX_SEMAPHORE
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
@@ -25,10 +32,6 @@
 #include <rtems/posix/time.h>
 #include <rtems/seterr.h>
 
-/*
- *  11.2.7 Unlock a Semaphore, P1003.1b-1993, p.227
- */
-
 int sem_post(
   sem_t  *sem
 )
diff --git a/cpukit/posix/src/semwait.c b/cpukit/posix/src/semwait.c
index 32b896a4df..16fc9076d4 100644
--- a/cpukit/posix/src/semwait.c
+++ b/cpukit/posix/src/semwait.c
@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Lock a Semaphore
+ *  @ingroup POSIX_SEMAPHORE
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
@@ -25,12 +32,6 @@
 #include <rtems/posix/time.h>
 #include <rtems/seterr.h>
 
-/*
- *  11.2.6 Lock a Semaphore, P1003.1b-1993, p.226
- *
- *  NOTE: P1003.4b/D8 adds sem_timedwait(), p. 27
- */
-
 int sem_wait(
   sem_t *sem
 )