posix: Doxygen Enhancement Task #2

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

cpukit/posix/include/mqueue.h

@@ -172,11 +172,12 @@ ssize_t mq_timedreceive(
 
 #if defined(_POSIX_REALTIME_SIGNALS)
 
-/*
- *  15.2.6 Notify Process that a Message is Available on a Queue,
- *         P1003.1b-1993, p. 280
+/**
+ * @brief Notify Process that a Message is Available on a Queue
+ *
+ * 15.2.6 Notify Process that a Message is Available on a Queue,
+ *        P1003.1b-1993, p. 280
  */
-
 int mq_notify(
   mqd_t                  mqdes,
   const struct sigevent *notification
@@ -184,10 +185,11 @@ int mq_notify(
 
 #endif /* _POSIX_REALTIME_SIGNALS */
 
-/*
- *  15.2.7 Set Message Queue Attributes, P1003.1b-1993, p. 281
+/**
+ * @brief Set Message Queue Attributes
+ *
+ * 15.2.7 Set Message Queue Attributes, P1003.1b-1993, p. 281
  */
-
 int mq_setattr(
   mqd_t                 mqdes,
   const struct mq_attr *mqstat,

cpukit/posix/include/rtems/posix/cond.h

@@ -148,15 +148,14 @@ int _POSIX_Condition_variables_Signal_support(
   bool                       is_broadcast
 );
 
-/*
- *  _POSIX_Condition_variables_Wait_support
+/**
+ * @brief POSIX Condition Variables Wait Support
  *
- *  DESCRIPTION:
+ * DESCRIPTION:
  *
- *  A support routine which implements guts of the blocking, non-blocking, and
- *  timed wait version of condition variable wait routines.
+ * A support routine which implements guts of the blocking, non-blocking, and
+ * timed wait version of condition variable wait routines.
  */
-
 int _POSIX_Condition_variables_Wait_support(
   pthread_cond_t            *cond,
   pthread_mutex_t           *mutex,

cpukit/posix/include/rtems/posix/psignalimpl.h

@@ -81,6 +81,11 @@ static inline void _POSIX_signals_Add_post_switch_extension(void)
   _API_extensions_Add_post_switch( &_POSIX_signals_Post_switch );
 }
 
+/**
+ * @brief POSIX Signals Thread Unlock
+ *
+ * XXX this routine could probably be cleaned up
+ */
 bool _POSIX_signals_Unblock_thread(
   Thread_Control  *the_thread,
   int              signo,

cpukit/posix/include/rtems/posix/pthread.h

@@ -30,6 +30,15 @@
 #ifdef __cplusplus
 extern "C" {
 #endif
+
+/**
+ * @defgroup POSIX_PTHREAD POSIX Threads Support
+ *
+ * @ingroup POSIX
+ *
+ * @brief Private Support Information for POSIX Threads
+ */
+
 /**
  *  The following sets the minimum stack size for POSIX threads.
  */
@@ -170,10 +179,10 @@ int _POSIX_Thread_Translate_sched_param(
 );
 
 /**
- *  @brief  _POSIX_Threads_Initialize_user_threads_body
+ * @brief POSIX Threads Initialize User Threads Body
  *
- *  This routine creates and starts all configured user
- *  initialization threads.
+ * This routine creates and starts all configured user
+ * initialization threads.
  */
 extern void _POSIX_Threads_Initialize_user_threads_body(void);
 

cpukit/posix/include/semaphore.h

@@ -74,15 +74,24 @@ sem_t *sem_open(
   ...
 );
 
-/*
- *  11.2.4 Close a Named Semaphore, P1003.1b-1993, p.224
+/**
+ * @brief Close a Named Semaphore
+ *
+ * Routine to close a semaphore that has been opened or initialized.
+ *
+ * 11.2.4 Close a Named Semaphore, P1003.1b-1993, p.224
  */
 int sem_close(
   sem_t *sem
 );
 
-/*
- *  11.2.5 Remove a Named Semaphore, P1003.1b-1993, p.225
+/**
+ * @brief Remove a Named Semaphore
+ *
+ * Unlinks a named semaphore, sem_close must also be called to remove
+ * the semaphore.
+ *
+ * 11.2.5 Remove a Named Semaphore, P1003.1b-1993, p.225
  */
 int sem_unlink(
   const char *name
@@ -124,10 +133,11 @@ int sem_post(
   sem_t  *sem
 );
 
-/*
- *  11.2.8 Get the Value of a Semaphore, P1003.1b-1993, p.229
+/**
+ * @brief Get the Value of a Semaphore
+ *
+ * 11.2.8 Get the Value of a Semaphore, P1003.1b-1993, p.229
  */
-
 int sem_getvalue(
   sem_t  *sem,
   int    *sval

cpukit/posix/src/condwaitsupp.c

@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief POSIX Condition Variables Wait Support
+ * @ingroup POSIX_COND_VARS
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
@@ -22,13 +29,6 @@
 #include <rtems/posix/time.h>
 #include <rtems/posix/mutex.h>
 
-/*
- *  _POSIX_Condition_variables_Wait_support
- *
- *  A support routine which implements guts of the blocking, non-blocking, and
- *  timed wait version of condition variable wait routines.
- */
-
 int _POSIX_Condition_variables_Wait_support(
   pthread_cond_t            *cond,
   pthread_mutex_t           *mutex,

cpukit/posix/src/mqueuenotify.c

@@ -1,16 +1,11 @@
+/**
+ * @file
+ *
+ * @brief Notify Process that a Message is Available on a Queue
+ * @ingroup POSIX_MQUEUE
+ */
+
 /*
- *  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.
- *
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -57,11 +52,6 @@ static void _POSIX_Message_queue_Notify_handler(
   _CORE_message_queue_Set_notify( &the_mq->Message_queue, NULL, NULL );
 }
 
-/*
- *  15.2.6 Notify Process that a Message is Available on a Queue,
- *         P1003.1b-1993, p. 280
- */
-
 int mq_notify(
   mqd_t                  mqdes,
   const struct sigevent *notification

cpukit/posix/src/mqueuesetattr.c

@@ -1,16 +1,11 @@
+/**
+ * @file
+ *
+ * @brief Set Message Queue Attributes
+ * @ingroup POSIX_MQUEUE
+ */
+
 /*
- *  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.
- *
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -37,10 +32,6 @@
 #include <rtems/posix/mqueue.h>
 #include <rtems/posix/time.h>
 
-/*
- *  15.2.7 Set Message Queue Attributes, P1003.1b-1993, p. 281
- */
-
 int mq_setattr(
   mqd_t                 mqdes,
   const struct mq_attr *mqstat,

cpukit/posix/src/mutexattrdestroy.c

@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief Destroy Mutex Attributes Object
+ * @ingroup POSIX
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
@@ -21,10 +28,9 @@
 #include <rtems/posix/priority.h>
 #include <rtems/posix/time.h>
 
-/*
- *  11.3.1 Mutex Initialization Attributes, P1003.1c/Draft 10, p. 81
+/**
+ * 11.3.1 Mutex Initialization Attributes, P1003.1c/Draft 10, p. 81
  */
-
 int pthread_mutexattr_destroy(
   pthread_mutexattr_t *attr
 )

cpukit/posix/src/mutexinit.c

@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief Initialize a Mutex
+ * @ingroup POSIX
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2009.
  *  On-Line Applications Research Corporation (OAR).
@@ -21,11 +28,11 @@
 #include <rtems/posix/priority.h>
 #include <rtems/posix/time.h>
 
-/*
- *  11.3.2 Initializing and Destroying a Mutex, P1003.1c/Draft 10, p. 87
+/**
+ * 11.3.2 Initializing and Destroying a Mutex, P1003.1c/Draft 10, p. 87
  *
- *  NOTE:  XXX Could be optimized so all the attribute error checking
- *             is not performed when attr is NULL.
+ * NOTE:  XXX Could be optimized so all the attribute error checking
+ *            is not performed when attr is NULL.
  */
 
 int pthread_mutex_init(

cpukit/posix/src/mutextimedlock.c

@@ -1,5 +1,8 @@
-/*
- *  Mutex Timed Lock
+/**
+ * @file
+ *
+ * @brief Mutex Timed Lock
+ * @ingroup POSIX
  */
 
 /*
@@ -28,12 +31,11 @@
 #include <rtems/posix/priority.h>
 #include <rtems/posix/time.h>
 
-/*
- *  11.3.3 Locking and Unlocking a Mutex, P1003.1c/Draft 10, p. 93
+/**
+ * 11.3.3 Locking and Unlocking a Mutex, P1003.1c/Draft 10, p. 93
  *
- *  NOTE: P1003.4b/D8 adds pthread_mutex_timedlock(), p. 29
+ * NOTE: P1003.4b/D8 adds pthread_mutex_timedlock(), p. 29
  */
-
 int pthread_mutex_timedlock(
   pthread_mutex_t       *mutex,
   const struct timespec *abstime

cpukit/posix/src/mutextrylock.c

@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief Try to Lock Mutex
+ * @ingroup POSIX
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
@@ -24,12 +31,11 @@
 #include <rtems/posix/priority.h>
 #include <rtems/posix/time.h>
 
-/*
- *  11.3.3 Locking and Unlocking a Mutex, P1003.1c/Draft 10, p. 93
+/**
+ * 11.3.3 Locking and Unlocking a Mutex, P1003.1c/Draft 10, p. 93
  *
- *  NOTE: P1003.4b/D8 adds pthread_mutex_timedlock(), p. 29
+ * NOTE: P1003.4b/D8 adds pthread_mutex_timedlock(), p. 29
  */
-
 int pthread_mutex_trylock(
   pthread_mutex_t           *mutex
 )

cpukit/posix/src/pause.c

@@ -1,6 +1,11 @@
-/*
- *  3.4.2 Suspend Process Execution, P1003.1b-1993, p. 81
+/**
+ * @file
  *
+ * @brief Suspend Process Execution
+ * @ingroup POSIX
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -17,10 +22,9 @@
 #include <signal.h>
 #include <unistd.h>
 
-/*
- *  3.4.2 Suspend Process Execution, P1003.1b-1993, p. 81
+/**
+ * 3.4.2 Suspend Process Execution, P1003.1b-1993, p. 81
  */
-
 int pause( void )
 {
   sigset_t  all_signals;

cpukit/posix/src/pbarrierwait.c

@@ -1,6 +1,11 @@
-/*
- *  POSIX Barrier Manager -- Wait at a Barrier
+/**
+ * @file
  *
+ * @brief Wait at a Barrier
+ * @ingroup POSIX
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -19,18 +24,14 @@
 #include <rtems/system.h>
 #include <rtems/posix/barrier.h>
 
-/*
- *  pthread_barrier_wait
+/**
+ * This directive allows a thread to wait at a barrier.
  *
- *  This directive allows a thread to wait at a barrier.
+ * @param[in] barrier is the barrier id
  *
- *  Input parameters:
- *    barrier    - barrier id
- *
- *  Output parameters:
- *    0                             - if successful
- *    PTHREAD_BARRIER_SERIAL_THREAD - if successful
- *    error code                    - if unsuccessful
+ * @retval 0 if successful
+ * @retval PTHREAD_BARRIER_SERIAL_THREAD if successful
+ * @retval error_code if unsuccessful
  */
 
 int pthread_barrier_wait(

cpukit/posix/src/prwlockrdlock.c

@@ -1,6 +1,11 @@
-/*
- *  POSIX RWLock Manager -- Obtain a Read Lock on a RWLock Instance
+/**
+ * @file
  *
+ * @brief Obtain a Read Lock on a RWLock Instance
+ * @ingroup POSIX
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -19,17 +24,13 @@
 #include <rtems/system.h>
 #include <rtems/posix/rwlock.h>
 
-/*
- *  pthread_rwlock_rdlock
+/**
+ * This directive attempts to obtain a read only lock on an rwlock instance.
  *
- *  This directive attempts to obtain a read only lock on an rwlock instance.
+ * @param[in] rwlock is the pointer to rwlock id
  *
- *  Input parameters:
- *    rwlock          - pointer to rwlock id
- *
- *  Output parameters:
- *    0          - if successful
- *    error code - if unsuccessful
+ * @retval 0 if successful
+ * @retval error_code if unsuccessful
  */
 
 int pthread_rwlock_rdlock(

cpukit/posix/src/psignalunblockthread.c

@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief POSIX Signals Thread Unlock
+ * @ingroup POSIX_SIGNALS
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
@@ -27,12 +34,6 @@
 #include <rtems/posix/time.h>
 #include <stdio.h>
 
-
-/*
- *  _POSIX_signals_Unblock_thread
- */
-
-/* XXX this routine could probably be cleaned up */
 bool _POSIX_signals_Unblock_thread(
   Thread_Control  *the_thread,
   int              signo,

cpukit/posix/src/pthreadattrinit.c

@@ -1,6 +1,11 @@
-/*
- *  16.1.1 Thread Creation Attributes, P1003.1c/Draft 10, p, 140
+/**
+ * @file
  *
+ * @brief Thread Attributes Creation
+ * @ingroup POSIX
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -19,6 +24,9 @@
 #include <rtems/system.h>
 #include <rtems/posix/pthread.h>
 
+/**
+ * 16.1.1 Thread Creation Attributes, P1003.1c/Draft 10, p, 140
+ */
 int pthread_attr_init(
   pthread_attr_t  *attr
 )

cpukit/posix/src/pthreaddetach.c

@@ -1,6 +1,11 @@
-/*
- *  16.1.4 Detaching a Thread, P1003.1c/Draft 10, p. 149
+/**
+ * @file
  *
+ * @brief Detaching a Thread
+ * @ingroup POSIX
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -20,6 +25,9 @@
 #include <rtems/score/thread.h>
 #include <rtems/posix/pthread.h>
 
+/**
+ * 16.1.4 Detaching a Thread, P1003.1c/Draft 10, p. 149
+ */
 int pthread_detach(
   pthread_t   thread
 )

cpukit/posix/src/pthreadinitthreads.c

@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief POSIX Threads Initialize User Threads Body
+ * @ingroup POSIX_PTHREAD
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
@@ -28,17 +35,6 @@
 #include <rtems/posix/key.h>
 #include <rtems/posix/time.h>
 
-/*
- *  _POSIX_Threads_Initialize_user_threads_body
- *
- *  This routine creates and starts all configured user
- *  initialization threads.
- *
- *  Input parameters: NONE
- *
- *  Output parameters:  NONE
- */
-
 void _POSIX_Threads_Initialize_user_threads_body(void)
 {
   int                                 status;

cpukit/posix/src/sched_getparam.c

@@ -1,6 +1,11 @@
-/*
- *  13.3.2 Set Scheduling Parameters, P1003.1b-1993, p. 253
+/**
+ * @file
  *
+ * @brief Set Scheduling Parameters
+ * @ingroup POSIX
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -19,6 +24,9 @@
 #include <rtems/system.h>
 #include <rtems/seterr.h>
 
+/**
+ * 13.3.2 Set Scheduling Parameters, P1003.1b-1993, p. 253
+ */
 int sched_getparam(
   pid_t                     pid __attribute__((unused)),
   struct sched_param       *param __attribute__((unused))

cpukit/posix/src/semclose.c

@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief Close a Named Semaphore
+ * @ingroup POSIX_SEMAPHORE
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
@@ -25,15 +32,6 @@
 #include <rtems/posix/time.h>
 #include <rtems/seterr.h>
 
-
-/*
- *  sem_close
- *
- *  Routine to close a semaphore that has been opened or initialized.
- *
- *  11.2.4 Close a Named Semaphore, P1003.1b-1993, p.224
- */
-
 int sem_close(
   sem_t *sem
 )

cpukit/posix/src/semgetvalue.c

@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief Get the Value of 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.8 Get the Value of a Semaphore, P1003.1b-1993, p.229
- */
-
 int sem_getvalue(
   sem_t  *sem,
   int    *sval

cpukit/posix/src/semunlink.c

@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief Remove a Named Semaphore
+ * @ingroup POSIX_SEMAPHORE
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
@@ -25,15 +32,6 @@
 #include <rtems/posix/time.h>
 #include <rtems/seterr.h>
 
-/*
- *  sem_unlink
- *
- *  Unlinks a named semaphore, sem_close must also be called to remove
- *  the semaphore.
- *
- *  11.2.5 Remove a Named Semaphore, P1003.1b-1993, p.225
- */
-
 int sem_unlink(
   const char *name
 )

cpukit/posix/src/sigprocmask.c

@@ -1,8 +1,11 @@
+/**
+ * @file
+ *
+ * @brief Examine and Change Blocked Signals
+ * @ingroup POSIX
+ */
+
 /*
- *  3.3.5 Examine and Change Blocked Signals, P1003.1b-1993, p. 73
- *
- *  NOTE: P1003.1c/D10, p. 37 adds pthread_sigmask().
- *
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -18,6 +21,11 @@
 #include <pthread.h>
 #include <signal.h>
 
+/**
+ * 3.3.5 Examine and Change Blocked Signals, P1003.1b-1993, p. 73
+ *
+ * NOTE: P1003.1c/D10, p. 37 adds pthread_sigmask().
+ */
 int sigprocmask(
   int               how,
   const sigset_t   *set,

cpukit/posix/src/wait.c

@@ -1,6 +1,11 @@
-/*
- *  waitpid() - POSIX 1003.1b 3.2.1
+/**
+ * @file
  *
+ * @brief Wait for Process to Change State 
+ * @ingroup POSIX
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *