posix: Doxygen Enhancement Task #8

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

23 files changed, 182 insertions, 57 deletions

diff --git a/cpukit/posix/include/rtems/posix/key.h b/cpukit/posix/include/rtems/posix/key.h
index ce4f093b13..edcaa42685 100644
--- a/cpukit/posix/include/rtems/posix/key.h
+++ b/cpukit/posix/include/rtems/posix/key.h
@@ -58,7 +58,7 @@ POSIX_EXTERN Objects_Information  _POSIX_Keys_Information;
 void _POSIX_Key_Manager_initialization(void);
 
 /**
- *  @brief _POSIX_Keys_Run_destructors
+ *  @brief Thread-Specific Data Key Create
  *
  *  This function executes all the destructors associated with the thread's
  *  keys.  This function will execute until all values have been set to NULL.
diff --git a/cpukit/posix/include/rtems/posix/mqueue.h b/cpukit/posix/include/rtems/posix/mqueue.h
index 9226d6f86e..582d5b73b2 100644
--- a/cpukit/posix/include/rtems/posix/mqueue.h
+++ b/cpukit/posix/include/rtems/posix/mqueue.h
@@ -35,6 +35,12 @@
 #include <rtems/score/object.h>
 #include <rtems/posix/posixapi.h>
 
+/**
+ *  @defgroup POSIX_MQUEUE_P Message Queues Private Support Information
+ *
+ *  @ingroup POSIX
+ */
+/**@{*/
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -73,11 +79,24 @@ POSIX_EXTERN Objects_Information  _POSIX_Message_queue_Information;
 POSIX_EXTERN Objects_Information  _POSIX_Message_queue_Information_fds;
 
 /*
- *  _POSIX_Message_queue_Manager_initialization
+ *  @brief Initializes message_queue Manager Related Data Structures
  *
  *  DESCRIPTION:
  *
  *  This routine performs the initialization necessary for this manager.
+ *
+ *  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.
+ *
  */
 
 void _POSIX_Message_queue_Manager_initialization(void);
@@ -113,11 +132,23 @@ void _POSIX_Message_queue_Delete(
 );
 
 /*
- *  _POSIX_Message_queue_Receive_support
+ *  @brief POSIX Message Queue Receive Support
  *
  *  DESCRIPTION:
  *
  *  This routine supports the various flavors of receiving a message.
+ *
+ *  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.
  */
 
 ssize_t _POSIX_Message_queue_Receive_support(
@@ -243,6 +274,6 @@ int _POSIX_Message_queue_Translate_core_message_queue_return_code(
 #ifdef __cplusplus
 }
 #endif
-
+/**@}*/
 #endif
 /*  end of include file */
diff --git a/cpukit/posix/include/rtems/posix/pthread.h b/cpukit/posix/include/rtems/posix/pthread.h
index 52ad486337..910bdc97ed 100644
--- a/cpukit/posix/include/rtems/posix/pthread.h
+++ b/cpukit/posix/include/rtems/posix/pthread.h
@@ -21,6 +21,12 @@
 #include <rtems/posix/config.h>
 #include <rtems/posix/threadsup.h>
 
+/**
+ *  @defgroup POSIX_PTHREADS Private Threads
+ *
+ *  @ingroup POSIX
+ */
+/**@{*/
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -176,6 +182,6 @@ extern void _POSIX_Threads_Initialize_user_threads_body(void);
 #ifdef __cplusplus
 }
 #endif
-
+/**@}*/
 #endif
 /*  end of include file */
diff --git a/cpukit/posix/include/rtems/posix/semaphore.h b/cpukit/posix/include/rtems/posix/semaphore.h
index 378b284c42..08ace7684f 100644
--- a/cpukit/posix/include/rtems/posix/semaphore.h
+++ b/cpukit/posix/include/rtems/posix/semaphore.h
@@ -17,6 +17,12 @@
 #ifndef _RTEMS_POSIX_SEMAPHORE_H
 #define _RTEMS_POSIX_SEMAPHORE_H
 
+/**
+ *  @defgroup POSIX_SEMAPHORES Semaphore
+ *
+ *  @ingroup POSIX
+ */
+/**@{*/
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -150,7 +156,7 @@ void _POSIX_Semaphore_Delete(
 );
 
 /*
- *  _POSIX_Semaphore_Wait_support
+ *  @brief POSIX Semaphore Wait Support
  *
  *  DESCRIPTION:
  *
diff --git a/cpukit/posix/src/condwait.c b/cpukit/posix/src/condwait.c
index 2540208e16..3162b4d97b 100644
--- a/cpukit/posix/src/condwait.c
+++ b/cpukit/posix/src/condwait.c
@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief Waiting on a Condition
+ * @ingroup POSIX
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/posix/src/execvp.c b/cpukit/posix/src/execvp.c
index 6b4d0e9a39..7712c8cef6 100644
--- a/cpukit/posix/src/execvp.c
+++ b/cpukit/posix/src/execvp.c
@@ -1,6 +1,11 @@
-/*
- *  execvp() - POSIX 1003.1b 3.1.2
+/**
+ * @file
  *
+ * @brief execvp() - POSIX 1003.1b 3.1.2
+ * @ingroup POSIX_KEY Key
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/posix/src/keyrundestructors.c b/cpukit/posix/src/keyrundestructors.c
index 888b24715a..9f48888bb8 100644
--- a/cpukit/posix/src/keyrundestructors.c
+++ b/cpukit/posix/src/keyrundestructors.c
@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief Thread-Specific Data Key Create
+ * @ingroup POSIX_KEY Key
+ */
+
 /*
  *  Copyright (c) 2010 embedded brains GmbH.
  *
diff --git a/cpukit/posix/src/kill.c b/cpukit/posix/src/kill.c
index ee59fe4b84..8a476e40ce 100644
--- a/cpukit/posix/src/kill.c
+++ b/cpukit/posix/src/kill.c
@@ -1,6 +1,11 @@
-/*
- *  3.3.2 Send a Signal to a Process, P1003.1b-1993, p. 68
+/**
+ * @file
  *
+ * @brief Send a Signal to a Process
+ * @ingroup POSIX
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/posix/src/mqueue.c b/cpukit/posix/src/mqueue.c
index 689de26c62..93d6f1bc5b 100644
--- a/cpukit/posix/src/mqueue.c
+++ b/cpukit/posix/src/mqueue.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 Initializes message_queue Manager Related Data Structures
+ * @ingroup POSIX_MQUEUE_P Message Queues Private Support Information
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/posix/src/mqueuerecvsupp.c b/cpukit/posix/src/mqueuerecvsupp.c
index f1c3102e1f..5cfce067c6 100644
--- a/cpukit/posix/src/mqueuerecvsupp.c
+++ b/cpukit/posix/src/mqueuerecvsupp.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 POSIX Message Queue Receive Support
+ * @ingroup POSIX_MQUEUE_P Message Queues Private Support Information
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2011.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/posix/src/mutexattrsetprioceiling.c b/cpukit/posix/src/mutexattrsetprioceiling.c
index f4c2da9b96..82c83cf80e 100644
--- a/cpukit/posix/src/mutexattrsetprioceiling.c
+++ b/cpukit/posix/src/mutexattrsetprioceiling.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/prwlocktryrdlock.c b/cpukit/posix/src/prwlocktryrdlock.c
index eb8c5f8f05..f8524e34d2 100644
--- a/cpukit/posix/src/prwlocktryrdlock.c
+++ b/cpukit/posix/src/prwlocktryrdlock.c
@@ -1,6 +1,11 @@
-/*
- *  POSIX RWLock Manager -- Attempt to Obtain a Read Lock on a RWLock Instance
+/**
+ * @file
  *
+ * @brief Attempt to Obtain a Read Lock on a RWLock Instance
+ * @ingroup POSIX
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/posix/src/pthread.c b/cpukit/posix/src/pthread.c
index 1773c24b69..873449a2da 100644
--- a/cpukit/posix/src/pthread.c
+++ b/cpukit/posix/src/pthread.c
@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief Private Support Information for POSIX Threads
+ * @ingroup POSIX_PTHREADS Private Threads
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2010.
  *  On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/posix/src/pthreadattrgetstackaddr.c b/cpukit/posix/src/pthreadattrgetstackaddr.c
index c877c1395d..dfdffbd662 100644
--- a/cpukit/posix/src/pthreadattrgetstackaddr.c
+++ b/cpukit/posix/src/pthreadattrgetstackaddr.c
@@ -1,6 +1,11 @@
-/*
- *  16.1.1 Thread Creation Attributes, P1003.1c/Draft 10, p, 140
+/**
+ * @file
  *
+ * @brief Thread Creation Attributes
+ * @ingroup POSIX
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/posix/src/pthreadattrsetguardsize.c b/cpukit/posix/src/pthreadattrsetguardsize.c
index 51390a7d12..7656d4fee9 100644
--- a/cpukit/posix/src/pthreadattrsetguardsize.c
+++ b/cpukit/posix/src/pthreadattrsetguardsize.c
@@ -1,6 +1,11 @@
-/*
- *  16.1.1 Thread Creation Attributes
+/**
+ * @file
  *
+ * @brief Thread Creation Attributes
+ * @ingroup POSIX
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2010.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/posix/src/pthreadattrsetschedparam.c b/cpukit/posix/src/pthreadattrsetschedparam.c
index fb56652db7..65e560198f 100644
--- a/cpukit/posix/src/pthreadattrsetschedparam.c
+++ b/cpukit/posix/src/pthreadattrsetschedparam.c
@@ -1,6 +1,11 @@
-/*
- *  13.5.1 Thread Creation Scheduling Parameters, P1003.1c/Draft 10, p. 120
+/**
+ * @file
  *
+ * @brief Thread Creation Scheduling Parameters
+ * @ingroup POSIX
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/posix/src/pthreadequal.c b/cpukit/posix/src/pthreadequal.c
index bc18e33a13..ce08b1ea88 100644
--- a/cpukit/posix/src/pthreadequal.c
+++ b/cpukit/posix/src/pthreadequal.c
@@ -1,6 +1,11 @@
-/*
- *  16.1.7 Compare Thread IDs, p1003.1c/Draft 10, p. 153
+/**
+ * @file
  *
+ * @brief Compare Thread IDs
+ * @ingroup POSIX
+ */
+
+/*
  *  NOTE:  POSIX does not define the behavior when either thread id is invalid.
  *
  *  COPYRIGHT (c) 1989-2007.
diff --git a/cpukit/posix/src/sched_setscheduler.c b/cpukit/posix/src/sched_setscheduler.c
index fcbc8fd3fd..f9b5c3f562 100644
--- a/cpukit/posix/src/sched_setscheduler.c
+++ b/cpukit/posix/src/sched_setscheduler.c
@@ -1,7 +1,11 @@
-/*
- *  13.3.3 Set Scheduling Policy and Scheduling Parameters,
- *         P1003.1b-1993, p. 254
+/**
+ * @file
  *
+ * @brief Set Scheduling Policy and Scheduling Parameters
+ * @ingroup POSIX
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/posix/src/semaphorewaitsupp.c b/cpukit/posix/src/semaphorewaitsupp.c
index 2ad1efe5af..5b215dad23 100644
--- a/cpukit/posix/src/semaphorewaitsupp.c
+++ b/cpukit/posix/src/semaphorewaitsupp.c
@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief POSIX Semaphore Wait Support
+ * @ingroup POSIX_SEMAPHORES Semaphore
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/posix/src/sigfillset.c b/cpukit/posix/src/sigfillset.c
index 75b0ede57e..32b1ef15d0 100644
--- a/cpukit/posix/src/sigfillset.c
+++ b/cpukit/posix/src/sigfillset.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/sigqueue.c b/cpukit/posix/src/sigqueue.c
index b1f6cee67e..8b65aba0cb 100644
--- a/cpukit/posix/src/sigqueue.c
+++ b/cpukit/posix/src/sigqueue.c
@@ -1,6 +1,11 @@
-/*
- *  3.3.9 Queue a Signal to a Process, P1003.1b-1993, p. 78
+/**
+ * @file
  *
+ * @brief Queue a Signal to a Process
+ * @ingroup POSIX
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/posix/src/sigwait.c b/cpukit/posix/src/sigwait.c
index cfb733034b..24afa80602 100644
--- a/cpukit/posix/src/sigwait.c
+++ b/cpukit/posix/src/sigwait.c
@@ -1,8 +1,11 @@
-/*
- *  3.3.8 Synchronously Accept a Signal, P1003.1b-1993, p. 76
- *
- *  NOTE: P1003.1c/D10, p. 39 adds sigwait().
+/**
+ * @file
  *
+ * @brief Synchronously Accept a Signal
+ * @ingroup POSIX
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/posix/src/ualarm.c b/cpukit/posix/src/ualarm.c
index 2a2f975d67..34ab0a41cc 100644
--- a/cpukit/posix/src/ualarm.c
+++ b/cpukit/posix/src/ualarm.c
@@ -1,6 +1,11 @@
-/*
- *  3.4.1 Schedule Alarm, P1003.1b-1993, p. 79
+/**
+ * @file
  *
+ * @brief Schedule Alarm
+ * @ingroup POSIX
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
  *