posix: Doxygen Enhancement Task #5

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

cpukit/posix/include/aio.h

@@ -23,6 +23,14 @@
 extern "C" {
 #endif
 
+/**
+ * @defgroup POSIX_AIO POSIX Asynchronous I/O Support
+ *
+ * @ingroup POSIX
+ *
+ * @brief POSIX Asynchronous Input and Output
+ */
+
 #if defined(_POSIX_ASYNCHRONOUS_IO)
 
 /*
@@ -126,10 +134,18 @@ ssize_t aio_return(
   const struct aiocb  *aiocbp
 );
 
-/*
+/**
+ *  @brief Cancel Asynchronous I/O Operation
+ * 
  *  6.7.7 Cancel Asynchronous I/O Operation, P1003.1b-1993, p. 163
+ * 
+ *  @param[in] filedes is the file descriptor
+ *  @param[in] aiocbp is the asynchronous I/O control block
+ * 
+ *  @return This method returns AIO_CANCELED if the requested operation(s)
+ *          were canceled. Otherwise, AIO_NOTCANCELED is returned indicating
+ *          that at least one of the requested operation(s) cannot be canceled
  */
-
 int aio_cancel(
   int            filedes,
   struct aiocb  *aiocbp

cpukit/posix/include/rtems/posix/mqueue.h

@@ -3,6 +3,18 @@
  *
  * This include file contains all the private support information for
  * POSIX Message Queues.
+ * 
+ *  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.
  */
 
 /*
@@ -27,6 +39,10 @@
 extern "C" {
 #endif
 
+/**
+ *  @ingroup POSIX_MQUEUE
+ */
+
 /*
  *  Data Structure used to manage a POSIX message queue
  */
@@ -84,15 +100,14 @@ int _POSIX_Message_queue_Create_support(
   POSIX_Message_queue_Control  **message_queue
 );
 
-/*
+/**
- *  _POSIX_Message_queue_Delete
+ *  @brief POSIX Delete Message Queue
  *
  *  DESCRIPTION:
  *
  *  This routine supports the mq_unlink and mq_close routines by
  *  doing most of the work involved with removing a message queue.
  */
-
 void _POSIX_Message_queue_Delete(
   POSIX_Message_queue_Control *the_mq
 );

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

@@ -71,6 +71,9 @@ extern API_extensions_Post_switch_control _POSIX_signals_Post_switch;
  *  Internal routines
  */
 
+/**
+ *  @brief POSIX Signals Manager Initialization
+ */
 void _POSIX_signals_Manager_Initialization(void);
 
 static inline void _POSIX_signals_Add_post_switch_extension(void)
@@ -107,6 +110,9 @@ int killinfo(
   const union sigval *value
 );
 
+/**
+ *  @brief POSIX Signals Set Process Signals
+ */
 void _POSIX_signals_Set_process_signals(
   sigset_t   mask
 );

cpukit/posix/include/rtems/posix/ptimer.h

@@ -88,13 +88,15 @@ int timer_gettime(
   struct itimerspec *value
 );
 
-/*
+/**
+ *  @brief Get Overrun Count for a POSIX Per-Process Timer
+ * 
+ *  The expiration of a timer must increase by one a counter.
+ *  After the signal handler associated to the timer finishes
+ *  its execution, _POSIX_Timer_TSR will have to set this counter to 0.
+ * 
  *  14.2.4 Per-Process Timers, P1003.1b-1993, p. 267
- *
- *  timer_getoverrun
- *
  */
-
 int timer_getoverrun(
   timer_t   timerid
 );

cpukit/posix/include/rtems/posix/semaphore.h

@@ -21,6 +21,10 @@
 extern "C" {
 #endif
 
+/**
+ * @ingroup POSIX_SEMAPHORE
+ */
+
 #include <semaphore.h>
 #include <rtems/score/coresem.h>
 #include <rtems/posix/posixapi.h>
@@ -134,14 +138,13 @@ int _POSIX_Semaphore_Create_support(
   POSIX_Semaphore_Control  **the_sem
 );
 
-/*
+/**
- *  _POSIX_Semaphore_Delete
+ *  @brief POSIX Delete Semaphore
  *
  *  DESCRIPTION:
  *
  *  This routine supports the sem_close and sem_unlink routines.
  */
-
 void _POSIX_Semaphore_Delete(
   POSIX_Semaphore_Control *the_semaphore
 );

cpukit/posix/include/rtems/posix/spinlock.h

@@ -27,6 +27,14 @@
 extern "C" {
 #endif
 
+/**
+ * @defgroup POSIX_SPINLOCK POSIX Spinlock Support
+ *
+ * @ingroup POSIX
+ *
+ * @brief Constants and Structures Associated with the POSIX Spinlock Manager
+ */
+
 #include <rtems/score/object.h>
 #include <rtems/score/corespinlock.h>
 
@@ -60,7 +68,7 @@ POSIX_EXTERN Objects_Information  _POSIX_Spinlock_Information;
 void _POSIX_Spinlock_Manager_initialization(void);
 
 /**
- *  @brief _POSIX_Spinlock_Translate_core_spinlock_return_code (
+ *  @brief POSIX Spinlock Translate Core Spinlock Return Code
  *
  *  This routine translates SuperCore Spinlock status codes into the
  *  corresponding POSIX ones.

cpukit/posix/include/semaphore.h

@@ -99,6 +99,11 @@ int sem_wait(
   sem_t *sem
 );
 
+/**
+ *  @brief Lock a Semaphore
+ * 
+ *  @see sem_wait()
+ */
 int sem_trywait(
   sem_t *sem
 );

cpukit/posix/src/aio_cancel.c

@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Cancel Asynchronous I/O Operation
+ *  @ingroup POSIX_AIO
+ */
+
 /*
  * Copyright 2010, Alin Rus <alin.codejunkie@gmail.com> 
  * 
@@ -17,23 +24,6 @@
 #include <rtems/system.h>
 #include <rtems/seterr.h>
 
-/* 
- *  aio_cancel
- *
- * Cancel an asynchronous I/O request
- *
- *  Input parameters:
- *        fildes - file descriptor
- *        aiocbp - asynchronous I/O control block
- *
- *  Output parameters: 
- *        AIO_CANCELED    - if the requested operation(s)
- *                          were canceled
- *        AIO_NOTCANCELED - if at least one of the requested
- *                          operation(s) cannot be canceled
- */
-
-
 int aio_cancel(int fildes, struct aiocb  *aiocbp)
 {
   rtems_aio_request_chain *r_chain;

cpukit/posix/src/barrierattrinit.c

@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Initialize the Barrier Attributes Object
+ *  @ingroup POSIX
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
@@ -16,10 +23,6 @@
 
 #include <rtems/system.h>
 
-/*
- *  Barrier Attributes Initialization
- */
-
 int pthread_barrierattr_init(
   pthread_barrierattr_t *attr
 )

cpukit/posix/src/barrierattrsetpshared.c

@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Set the Process-Shared Attribute of the Barrier Attributes Object
+ *  @ingroup POSIX
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
@@ -14,10 +21,6 @@
 #include <pthread.h>
 #include <errno.h>
 
-/*
- *  Barrier Attributes Set Process Shared
- */
-
 int pthread_barrierattr_setpshared(
   pthread_barrierattr_t *attr,
   int                    pshared

cpukit/posix/src/condbroadcast.c

@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Broadcast 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_broadcast(
   pthread_cond_t   *cond
 )

cpukit/posix/src/condinit.c

@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Initialize 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_init(
   pthread_cond_t           *cond,
   const pthread_condattr_t *attr

cpukit/posix/src/execle.c

@@ -1,6 +1,11 @@
-/*
+/**
- *  execle() - POSIX 1003.1b 3.1.2
+ *  @file
  *
+ *  @brief Execute a File
+ *  @ingroup POSIX
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *

cpukit/posix/src/mqueuedeletesupp.c

@@ -1,16 +1,11 @@
+/**
+ *  @file
+ *
+ *  @brief POSIX Delete Message 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-2009.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -41,10 +36,6 @@
   #include <rtems/bspIo.h>
 #endif
 
-/*
- *  _POSIX_Message_queue_Delete
- */
-
 void _POSIX_Message_queue_Delete(
   POSIX_Message_queue_Control *the_mq
 )

cpukit/posix/src/mutexattrinit.c

@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Mutex Initialization Attribute
+ *  @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
  */
-
 int pthread_mutexattr_init(
   pthread_mutexattr_t *attr
 )

cpukit/posix/src/pbarrierdestroy.c

@@ -1,6 +1,11 @@
-/*
+/**
- *  POSIX Barrier Manager -- Destroy a Barrier
+ *  @file
  *
+ *  @brief Destroy a Barrier Object 
+ *  @ingroup POSIX
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -19,21 +24,17 @@
 #include <rtems/system.h>
 #include <rtems/posix/barrier.h>
 
-/*
+/**
- *  pthread_barrier_destroy
- *
  *  This directive allows a thread to delete a barrier specified by
  *  the barrier id.  The barrier is freed back to the inactive
  *  barrier chain.
  *
- *  Input parameters:
+ *  @param[in] barrier is the barrier id
- *    barrier - barrier id
  * 
- *  Output parameters:
+ *  @return This method returns 0 if there was not an
- *    0           - if successful
+ *  error. Otherwise, a status code is returned indicating the
- *    error code  - if unsuccessful
+ *  source of the error.
  */
-
 int pthread_barrier_destroy(
   pthread_barrier_t *barrier
 )

cpukit/posix/src/psignal.c

@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief POSIX Signals Manager Initialization
+ *  @ingroup POSIX_SIGNALS
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
@@ -162,10 +169,6 @@ API_extensions_Post_switch_control _POSIX_signals_Post_switch = {
   .hook = _POSIX_signals_Post_switch_hook
 };
 
-/*
- *  _POSIX_signals_Manager_Initialization
- */
-
 void _POSIX_signals_Manager_Initialization(void)
 {
   uint32_t   signo;

cpukit/posix/src/psignalsetprocesssignals.c

@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief POSIX Signals Set Process Signals
+ *  @ingroup POSIX_SIGNALS
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
@@ -27,10 +34,6 @@
 #include <rtems/posix/time.h>
 #include <stdio.h>
 
-/*
- *  _POSIX_signals_Set_process_signals
- */
-
 void _POSIX_signals_Set_process_signals(
   sigset_t   mask
 )

cpukit/posix/src/pspindestroy.c

@@ -1,6 +1,11 @@
-/*
+/**
- *  POSIX Spinlock Manager -- Destroy a Spinlock
+ *  @file
  *
+ *  @brief Destroy a Spinlock
+ *  @ingroup POSIX
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -19,21 +24,17 @@
 #include <rtems/system.h>
 #include <rtems/posix/spinlock.h>
 
-/*
+/**
- *  pthread_spin_destroy
- *
  *  This directive allows a thread to delete a spinlock specified by
  *  the spinlock id.  The spinlock is freed back to the inactive
  *  spinlock chain.
  *
- *  Input parameters:
+ *  @param[in] spinlock is the spinlock id
- *    spinlock - spinlock id
  *
- *  Output parameters:
+ *  @return This method returns 0 if there was not an
- *    0           - if successful
+ *  error. Otherwise, a status code is returned indicating the
- *    error code  - if unsuccessful
+ *  source of the error.
  */
-
 int pthread_spin_destroy(
   pthread_spinlock_t *spinlock
 )

cpukit/posix/src/pspinlocktranslatereturncode.c

@@ -1,6 +1,11 @@
-/*
+/**
- *  Spinlock Manager -- Translate SuperCore Status
+ *  @file
  *
+ *  @brief POSIX Spinlock Translate Core Spinlock Return Code
+ *  @ingroup POSIX_SPINLOCK
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -20,17 +25,6 @@
 #include <rtems/score/corespinlock.h>
 #include <rtems/posix/spinlock.h>
 
-/*
- *  _POSIX_Spinlock_Translate_core_spinlock_return_code
- *
- *  Input parameters:
- *    the_spinlock_status - spinlock status code to translate
- *
- *  Output parameters:
- *    status code - translated POSIX status code
- *
- */
-
 static int _POSIX_Spinlock_Return_codes[CORE_SPINLOCK_STATUS_LAST + 1] = {
   0,                        /* CORE_SPINLOCK_SUCCESSFUL */
   EDEADLK,                  /* CORE_SPINLOCK_HOLDER_RELOCKING */

cpukit/posix/src/rwlockattrgetpshared.c

@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief Get the Process-Shared Attribute of the RWLock
+ *  @ingroup POSIX
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
@@ -14,10 +21,6 @@
 #include <pthread.h>
 #include <errno.h>
 
-/*
- *  RWLock Attributes Get Process Shared
- */
-
 int pthread_rwlockattr_getpshared(
   const pthread_rwlockattr_t *attr,
   int                         *pshared

cpukit/posix/src/sched_getprioritymin.c

@@ -1,6 +1,11 @@
-/*
+/**
- *  13.3.6 Get Scheduling Parameter Limits, P1003.1b-1993, p. 258
+ *  @file
  *
+ *  @brief Get the Minimum Priority Limit 
+ *  @ingroup POSIX
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -20,6 +25,9 @@
 #include <rtems/seterr.h>
 #include <rtems/posix/priority.h>
 
+/**
+ *  13.3.6 Get Scheduling Parameter Limits, P1003.1b-1993, p. 258
+ */
 int sched_get_priority_min(
   int  policy
 )

cpukit/posix/src/semaphoredeletesupp.c

@@ -1,3 +1,10 @@
+/**
+ *  @file
+ *
+ *  @brief POSIX Delete 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>
 
-/*
- *  _POSIX_Semaphore_Delete
- */
-
 void _POSIX_Semaphore_Delete(
   POSIX_Semaphore_Control *the_semaphore
 )

cpukit/posix/src/semtrywait.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_trywait(
   sem_t *sem
 )

cpukit/posix/src/sigtimedwait.c

@@ -1,6 +1,11 @@
-/*
+/**
- *  3.3.8 Synchronously Accept a Signal, P1003.1b-1993, p. 76
+ *  @file
  *
+ *  @brief Wait for Queued Signals
+ *  @ingroup POSIX
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -58,6 +63,9 @@ found_it:
   return signo;
 }
 
+/**
+ *  3.3.8 Synchronously Accept a Signal, P1003.1b-1993, p. 76
+ */
 int sigtimedwait(
   const sigset_t         *set,
   siginfo_t              *info,

cpukit/posix/src/timergetoverrun.c

@@ -1,6 +1,11 @@
-/*
+/**
- *  14.2.4 Per-Process Timers, P1003.1b-1993, p. 267
+ *  @file
  *
+ *  @brief Get Overrun Count for a POSIX Per-Process Timer
+ *  @ingroup POSIX_PRIV_TIMERS
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -21,13 +26,6 @@
 #include <rtems/score/thread.h>
 #include <rtems/posix/timer.h>
 
-/*
- * timer_getoverrun
- *
- * The expiration of a timer must increase by one a counter.
- * After the signal handler associated to the timer finishes
- * its execution, _POSIX_Timer_TSR will have to set this counter to 0.
- */
 int timer_getoverrun(
   timer_t   timerid
 )

cpukit/posix/src/waitpid.c

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