posix: Doxygen Enhancement Task #1

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

6 files changed, 85 insertions, 11 deletions

diff --git a/cpukit/posix/include/mqueue.h b/cpukit/posix/include/mqueue.h
index 56a97a0c7a..f41866bfe5 100644
--- a/cpukit/posix/include/mqueue.h
+++ b/cpukit/posix/include/mqueue.h
@@ -2,6 +2,18 @@
  * @file mqueue.h
  *
  * This file contains the definitions related to 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.
  */
 
 /*
@@ -115,6 +127,13 @@ int mq_send(
 
 #include <time.h>
 
+/**
+ *  @brief Send a Message to a Message Queue
+ * 
+ *  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,
@@ -125,12 +144,13 @@ int mq_timedsend(
 
 #endif /* _POSIX_TIMEOUTS */
 
-/*
+/**
+ *  @brief Receive a Message From a Message Queue 
+ * 
  *  15.2.5 Receive a Message From a Message Queue, P1003.1b-1993, p. 279
  *
- *  NOTE: P1003.4b/D8, p. 45 adds mq_timedreceive().
+ *  @note P1003.4b/D8, p. 45 adds mq_timedreceive().
  */
-
 ssize_t mq_receive(
   mqd_t         mqdes,
   char         *msg_ptr,
diff --git a/cpukit/posix/include/rtems/posix/mutex.h b/cpukit/posix/include/rtems/posix/mutex.h
index dc133d5421..0d73022f95 100644
--- a/cpukit/posix/include/rtems/posix/mutex.h
+++ b/cpukit/posix/include/rtems/posix/mutex.h
@@ -21,6 +21,14 @@
 extern "C" {
 #endif
 
+/**
+ * @defgroup POSIX_MUTEX POSIX Mutex Support
+ *
+ * @ingroup POSIX
+ *
+ * @brief Private Support Information for POSIX Mutex
+ */
+
 #include <rtems/score/coremutex.h>
 #include <pthread.h>
 
@@ -129,13 +137,17 @@ int _POSIX_Mutex_Lock_support(
   Watchdog_Interval          timeout
 );
 
-/*
- *  _POSIX_Mutex_Translate_core_mutex_return_code
+/**
+ *  @brief POSIX Mutex Translate Core Mutex Return Code
  *
  *  DESCRIPTION:
  *
  *  A support routine which converts core mutex status codes into the
  *  appropriate POSIX status values.
+ * 
+ *  @param[in] the_mutex_status is the mutex status code to translate
+ * 
+ *  @return the translated POSIX status code
  */
 
 int _POSIX_Mutex_Translate_core_mutex_return_code(
diff --git a/cpukit/posix/include/rtems/posix/priority.h b/cpukit/posix/include/rtems/posix/priority.h
index 62ec9fbe2d..a6a3c289da 100644
--- a/cpukit/posix/include/rtems/posix/priority.h
+++ b/cpukit/posix/include/rtems/posix/priority.h
@@ -17,6 +17,14 @@
 #ifndef _RTEMS_POSIX_PRIORITY_H
 #define _RTEMS_POSIX_PRIORITY_H
 
+/**
+ * @defgroup POSIX_PRIORITY POSIX Priority Support
+ *
+ * @ingroup POSIX
+ *
+ * @brief Interface to the POSIX Priority Implementation
+ */
+
 #include <rtems/score/priority.h>
 
 /**
@@ -44,6 +52,8 @@
 #define POSIX_SCHEDULER_MINIMUM_PRIORITY (1)
 
 /**
+ *  @brief POSIX Is Priority Valid
+ * 
  *  1003.1b-1993,2.2.2.80 definition of priority, p. 19
  *
  *  "Numerically higher values represent higher priorities."
diff --git a/cpukit/posix/include/rtems/posix/psignalimpl.h b/cpukit/posix/include/rtems/posix/psignalimpl.h
index 6c46f3c49c..d9ba88427a 100644
--- a/cpukit/posix/include/rtems/posix/psignalimpl.h
+++ b/cpukit/posix/include/rtems/posix/psignalimpl.h
@@ -16,6 +16,14 @@
 #ifndef _RTEMS_POSIX_PSIGNALIMPL_H
 #define _RTEMS_POSIX_PSIGNALIMPL_H
 
+/**
+ * @defgroup POSIX_SIGNALS POSIX Signals Support
+ *
+ * @ingroup POSIX
+ *
+ * @brief Internal Information about POSIX Signals
+ */
+
 #include <rtems/posix/psignal.h>
 #include <rtems/posix/pthread.h>
 #include <rtems/posix/sigset.h>
@@ -76,6 +84,9 @@ bool _POSIX_signals_Unblock_thread(
   siginfo_t       *info
 );
 
+/**
+ *  @brief POSIX Signals Check Signal
+ */
 bool _POSIX_signals_Check_signal(
   POSIX_API_Control  *api,
   int                 signo,
diff --git a/cpukit/posix/include/rtems/posix/rwlock.h b/cpukit/posix/include/rtems/posix/rwlock.h
index c4f2d7e146..411384c2c6 100644
--- a/cpukit/posix/include/rtems/posix/rwlock.h
+++ b/cpukit/posix/include/rtems/posix/rwlock.h
@@ -27,6 +27,14 @@
 extern "C" {
 #endif
 
+/**
+ * @defgroup POSIX_RWLOCK POSIX RWLock Manager
+ *
+ * @ingroup POSIX
+ *
+ * @brief Constants and Structures Associated with the POSIX RWLock Manager
+ */
+
 #include <rtems/score/object.h>
 #include <rtems/score/corerwlock.h>
 
@@ -60,7 +68,7 @@ POSIX_EXTERN Objects_Information  _POSIX_RWLock_Information;
 void _POSIX_RWLock_Manager_initialization(void);
 
 /**
- *  @brief _POSIX_RWLock_Translate_core_RWLock_return_code (
+ *  @brief POSIX RWLock Translate Core RWLock Return Code
  *
  *  This routine translates SuperCore RWLock status codes into the
  *  corresponding POSIX ones.
diff --git a/cpukit/posix/include/semaphore.h b/cpukit/posix/include/semaphore.h
index 91722006ce..1dc82bedef 100644
--- a/cpukit/posix/include/semaphore.h
+++ b/cpukit/posix/include/semaphore.h
@@ -21,6 +21,14 @@
 extern "C" {
 #endif
 
+/**
+ * @defgroup POSIX_SEMAPHORE POSIX Semaphores Support
+ *
+ * @ingroup POSIX
+ *
+ * @brief Private Support Information for POSIX Semaphores
+ */
+
 #include <unistd.h>
 
 #if defined(_POSIX_SEMAPHORES)
@@ -46,7 +54,9 @@ int sem_init(
   unsigned int   value
 );
 
-/*
+/**
+ *  @brief Destroy an Unnamed Semaphore
+ * 
  *  11.2.2 Destroy an Unnamed Semaphore, P1003.1b-1993, p.220
  */
 int sem_destroy(
@@ -78,10 +88,12 @@ int sem_unlink(
   const char *name
 );
 
-/*
+/**
+ *  @brief Lock a Semaphore
+ * 
  *  11.2.6 Lock a Semaphore, P1003.1b-1993, p.226
  *
- *  NOTE: P1003.4b/D8 adds sem_timedwait(), p. 27
+ *  @note P1003.4b/D8 adds sem_timedwait(), p. 27
  */
 int sem_wait(
   sem_t *sem
@@ -98,10 +110,11 @@ int sem_timedwait(
 );
 #endif
 
-/*
+/**
+ *  @brief Unlock a Semaphore
+ * 
  *  11.2.7 Unlock a Semaphore, P1003.1b-1993, p.227
  */
-
 int sem_post(
   sem_t  *sem
 );