posix: Doxygen Clean Up Task #1

20 files changed, 419 insertions, 345 deletions

diff --git a/cpukit/posix/include/aio.h b/cpukit/posix/include/aio.h
index 3ad7a400e6..769f0b37f2 100644
--- a/cpukit/posix/include/aio.h
+++ b/cpukit/posix/include/aio.h
@@ -31,6 +31,8 @@ extern "C" {
  * @ingroup POSIX
  *
  * @brief POSIX Asynchronous Input and Output
+ * 
+ * @{
  */
 
 #if defined(_POSIX_ASYNCHRONOUS_IO)
@@ -137,16 +139,18 @@ ssize_t aio_return(
 );
 
 /**
- *  @brief Cancel Asynchronous I/O Operation
+ * @brief Cancel asynchronous I/O operation.
  * 
- *  6.7.7 Cancel Asynchronous I/O Operation, P1003.1b-1993, p. 163
+ * 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
+ * @param[in] filedes is the file descriptor
+ * @param[in] aiocbp is a pointer to 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
+ * @retval AIO_CANCELED The requested operation(s) were canceled. 
+ * @retval AIO_NOTCANCELED Some of the requested operation(s) cannot be
+ * canceled since they are in progress.
+ * @retval AIO_ALLDONE None of the requested operation(s) could be canceled
+ * since they are already complete
  */
 int aio_cancel(
   int            filedes,
@@ -178,6 +182,8 @@ int aio_fsync(
 
 #endif /* _POSIX_ASYNCHRONOUS_IO */
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/cpukit/posix/include/mqueue.h b/cpukit/posix/include/mqueue.h
index 0f937f5f2b..a3e43ee712 100644
--- a/cpukit/posix/include/mqueue.h
+++ b/cpukit/posix/include/mqueue.h
@@ -41,11 +41,12 @@
 #include <rtems/score/object.h>
 
 /**
- *  @defgroup POSIX_MQUEUE Message Queues
+ * @defgroup POSIX_MQUEUE POSIX Message Queues
  *
- *  @ingroup POSIX
+ * @ingroup POSIX
+ * 
+ * @{
  */
-/**@{*/
 
 #ifdef __cplusplus
 extern "C" {
@@ -56,14 +57,14 @@ extern "C" {
  */
 
 /**
- *  Message queue id type.
+ * Message queue id type.
  *
- *  @note Use uint32_t since all POSIX Ids are 32-bit currently.
+ * NOTE: Use uint32_t since all POSIX Ids are 32-bit currently.
  */
 typedef uint32_t  mqd_t;
 
 /**
- *  This is the message queue attributes structure.
+ * This is the message queue attributes structure.
  */
 struct mq_attr {
   /** This is the message queue flags */
@@ -77,7 +78,7 @@ struct mq_attr {
 };
 
 /**
- *  15.2.2 Open a Message Queue, P1003.1b-1993, p. 272
+ * 15.2.2 Open a Message Queue, P1003.1b-1993, p. 272
  */
 mqd_t mq_open(
   const char *name,
@@ -86,37 +87,37 @@ mqd_t mq_open(
 );
 
 /**
- *  15.2.2 Close a Message Queue, P1003.1b-1993, p. 275
+ * 15.2.2 Close a Message Queue, P1003.1b-1993, p. 275
  */
 int mq_close(
   mqd_t  mqdes
 );
 
 /**
- *  @brief Remove a Message Queue
+ * @brief Remove a message queue.
  *
- *  15.2.2 Remove a Message Queue, P1003.1b-1993, p. 276
+ * 15.2.2 Remove a Message Queue, P1003.1b-1993, p. 276
  *
- *  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.]
+ * 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.
+ *        This code ignores the O_RDONLY/O_WRONLY/O_RDWR flag at open
+ *        time.
  */
 int mq_unlink(
   const char *name
 );
 
 /**
- *  15.2.4 Send a Message to a Message Queue, P1003.1b-1993, p. 277
+ * 15.2.4 Send a Message to a Message Queue, P1003.1b-1993, p. 277
  *
- *  @note P1003.4b/D8, p. 45 adds mq_timedsend().
+ * NOTE; P1003.4b/D8, p. 45 adds mq_timedsend().
  */
 int mq_send(
   mqd_t         mqdes,
@@ -130,11 +131,9 @@ int mq_send(
 #include <time.h>
 
 /**
- *  @brief Send a Message to a Message Queue
+ * @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().
+ * @see mq_send()
  */
 int mq_timedsend(
   mqd_t                  mqdes,
@@ -147,11 +146,11 @@ int mq_timedsend(
 #endif /* _POSIX_TIMEOUTS */
 
 /**
- *  @brief Receive a Message From a Message Queue 
+ * @brief Receive a message from a message queue. 
  * 
- *  15.2.5 Receive a Message From a Message Queue, P1003.1b-1993, p. 279
+ * 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,
@@ -175,7 +174,7 @@ ssize_t mq_timedreceive(
 #if defined(_POSIX_REALTIME_SIGNALS)
 
 /**
- * @brief Notify Process that a Message is Available on a Queue
+ * @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
@@ -188,7 +187,7 @@ int mq_notify(
 #endif /* _POSIX_REALTIME_SIGNALS */
 
 /**
- * @brief Set Message Queue Attributes
+ * @brief Set message queue attributes.
  *
  * 15.2.7 Set Message Queue Attributes, P1003.1b-1993, p. 281
  */
@@ -207,11 +206,13 @@ int mq_getattr(
   struct mq_attr *mqstat
 );
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif
 
 #endif /* _POSIX_MESSAGE_PASSING */
-/**@}*/
+
 #endif
 /* end of include file */
diff --git a/cpukit/posix/include/rtems/posix/aio_misc.h b/cpukit/posix/include/rtems/posix/aio_misc.h
index da926086ac..4dfcb592c2 100644
--- a/cpukit/posix/include/rtems/posix/aio_misc.h
+++ b/cpukit/posix/include/rtems/posix/aio_misc.h
@@ -1,5 +1,7 @@
 /**
- * @file rtems/posix/aio_misc.h
+ * @file
+ * 
+ * @brief POSIX Asynchronous Input and Output Private Support
  *
  * This defines private information for the AIO implementation.
  */
diff --git a/cpukit/posix/include/rtems/posix/barrier.h b/cpukit/posix/include/rtems/posix/barrier.h
index e5de9dceaa..41a297e13e 100644
--- a/cpukit/posix/include/rtems/posix/barrier.h
+++ b/cpukit/posix/include/rtems/posix/barrier.h
@@ -1,14 +1,16 @@
 /**
- * @file rtems/posix/barrier.h
+ * @file
+ * 
+ * @brief Constants and Structures Associated with the POSIX Barrier Manager
  *
- *  This include file contains all the constants and structures associated
- *  with the POSIX Barrier Manager.
+ * This include file contains all the constants and structures associated
+ * with the POSIX Barrier Manager.
  *
- *  Directives provided are:
+ * Directives provided are:
  *
- *   - create a barrier
- *   - delete a barrier
- *   - wait for a barrier
+ *  - create a barrier
+ *  - delete a barrier
+ *  - wait for a barrier
  */
 
 /*
@@ -24,14 +26,15 @@
 #define _RTEMS_POSIX_BARRIER_H
 
 /**
- *  @defgroup POSIXBarrier POSIX Barriers
+ * @defgroup POSIXBarrier POSIX Barriers
  *
- *  @ingroup POSIXAPI
+ * @ingroup POSIXAPI
  *
- *  This encapsulates functionality which implements the RTEMS API
- *  Barrier Manager.
+ * This encapsulates functionality which implements the RTEMS API
+ * Barrier Manager.
+ * 
+ * @{
  */
-/**@{*/
 
 #ifdef __cplusplus
 extern "C" {
@@ -41,7 +44,7 @@ extern "C" {
 #include <rtems/score/corebarrier.h>
 
 /**
- *  This type defines the control block used to manage each barrier.
+ * This type defines the control block used to manage each barrier.
  */
 
 typedef struct {
@@ -59,26 +62,22 @@ typedef struct {
 POSIX_EXTERN Objects_Information  _POSIX_Barrier_Information;
 
 /**
- *  @brief _POSIX_Barrier_Manager_initialization
+ * @brief POSIX barrier manager initialization.
  *
- *  This routine performs the initialization necessary for this manager.
- *
- *  @param[in] maximum_barriers is the total number of barriers allowed to
- *             concurrently be active in the system.
+ * This routine performs the initialization necessary for this manager.
  */
 
 void _POSIX_Barrier_Manager_initialization(void);
 
 /**
- *  @brief _POSIX_Barrier_Translate_core_barrier_return_code (
- *
- *  This routine translates SuperCore Barrier status codes into the
- *  corresponding POSIX ones.
- *
+ * @brief POSIX translate barrier return code.
+ * 
+ * This routine translates SuperCore Barrier status codes into the
+ * corresponding POSIX ones.
  *
- *  @param[in] the_barrier_status is the SuperCore status.
+ * @param[in] the_barrier_status is the SuperCore status.
  *
- *  @return the corresponding POSIX status
+ * @return the corresponding POSIX status
  */
 int _POSIX_Barrier_Translate_core_barrier_return_code(
   CORE_barrier_Status  the_barrier_status
@@ -88,11 +87,11 @@ int _POSIX_Barrier_Translate_core_barrier_return_code(
 #include <rtems/posix/barrier.inl>
 #endif
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif
 
-/**@}*/
-
 #endif
 /*  end of include file */
diff --git a/cpukit/posix/include/rtems/posix/cancel.h b/cpukit/posix/include/rtems/posix/cancel.h
index 06b8efd645..c1fff9c04d 100644
--- a/cpukit/posix/include/rtems/posix/cancel.h
+++ b/cpukit/posix/include/rtems/posix/cancel.h
@@ -1,5 +1,7 @@
 /**
- * @file rtems/posix/cancel.h
+ * @file
+ * 
+ * @brief POSIX Thread Cancelation Support
  *
  * This file contains the prototypes and data types used to implement
  * POSIX thread cancelation.
@@ -20,7 +22,7 @@
 #include <rtems/posix/threadsup.h>
 
 /**
- *  This structure is used to manage the cancelation handlers.
+ * This structure is used to manage the cancelation handlers.
  */
 typedef struct {
   /** This field is the Chain Node so we can put these on lists. */
@@ -32,25 +34,25 @@ typedef struct {
 }  POSIX_Cancel_Handler_control;
 
 /**
- *  @brief _POSIX_Threads_cancel_run
+ * @brief POSIX run thread cancelation.
  *
- *  This support routine runs through the chain of cancel handlers that
- *  have been registered and executes them.
+ * This support routine runs through the chain of cancel handlers that
+ * have been registered and executes them.
  *
- *  @param[in] the_thread is the thread whose cancelation handlers
- *             should be run
+ * @param[in] the_thread is a pointer to the thread whose cancelation handlers
+ *            should be run
  */
 void _POSIX_Threads_cancel_run(
   Thread_Control *the_thread
 );
 
 /**
- *  @brief _POSIX_Thread_Evaluate_cancellation_and_enable_dispatch
+ * @brief POSIX evaluate thread cancelation and enable dispatch. 
  *
- *  This routine separates a piece of code that existed as part of
- *  another routine, but had to be separated to improve coverage.
+ * This routine separates a piece of code that existed as part of
+ * another routine, but had to be separated to improve coverage.
  *
- *  @param[in] the_thread is the thread to evaluate canceling
+ * @param[in] the_thread is a pointer to the thread to evaluate canceling
  */
 void _POSIX_Thread_Evaluate_cancellation_and_enable_dispatch (
   Thread_Control *the_thread
diff --git a/cpukit/posix/include/rtems/posix/cond.h b/cpukit/posix/include/rtems/posix/cond.h
index 93b5b4cf2a..5fdc1a1a31 100644
--- a/cpukit/posix/include/rtems/posix/cond.h
+++ b/cpukit/posix/include/rtems/posix/cond.h
@@ -1,5 +1,7 @@
 /**
- * @file rtems/posix/cond.h
+ * @file
+ * 
+ * @brief POSIX Condition Variables Private Support
  *
  * This include file contains all the private support information for
  * POSIX condition variables.
@@ -18,11 +20,12 @@
 #define _RTEMS_POSIX_COND_H
 
 /**
- *  @defgroup POSIX_COND_VARS Condition Variables
+ * @defgroup POSIX_COND_VARS POSIX Condition Variables
  *
- *  @ingroup POSIX
+ * @ingroup POSIX
+ * 
+ * @{
  */
-/**@{*/
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -132,24 +135,21 @@ RTEMS_INLINE_ROUTINE bool _POSIX_Condition_variables_Is_null (
   POSIX_Condition_variables_Control *the_condition_variable
 );
 
-/*
- * @brief Implements wake up version of the "signal" operation
- *
- *  _POSIX_Condition_variables_Signal_support
- *
- *  DESCRIPTION:
+/**
+ * @brief Implements wake up version of the "signal" operation.
+ * 
+ * DESCRIPTION:
  *
- *  A support routine which implements guts of the broadcast and single task
- *  wake up version of the "signal" operation.
+ * A support routine which implements guts of the broadcast and single task
+ * wake up version of the "signal" operation.
  */
-
 int _POSIX_Condition_variables_Signal_support(
   pthread_cond_t            *cond,
   bool                       is_broadcast
 );
 
 /**
- * @brief POSIX Condition Variables Wait Support
+ * @brief POSIX condition variables wait support.
  *
  * DESCRIPTION:
  *
@@ -180,9 +180,11 @@ POSIX_Condition_variables_Control *_POSIX_Condition_variables_Get (
 
 #include <rtems/posix/cond.inl>
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif
-/**@}*/
+
 #endif
 /*  end of include file */
diff --git a/cpukit/posix/include/rtems/posix/config.h b/cpukit/posix/include/rtems/posix/config.h
index ddd63acae6..460ddcb2a9 100644
--- a/cpukit/posix/include/rtems/posix/config.h
+++ b/cpukit/posix/include/rtems/posix/config.h
@@ -1,6 +1,8 @@
 /**
- * @file rtems/posix/config.h
+ * @file
  *
+ * @brief User Defined Configuration Parameters Specific For The POSIX API
+ * 
  * This include file contains the table of user defined configuration
  * parameters specific for the POSIX API.
  */
@@ -60,10 +62,10 @@ typedef struct {
 } posix_api_configuration_table;
 
 /**
- *  @brief POSIX API Configuration Table
+ * @brief POSIX API configuration table.
  *
- *  This is the POSIX API Configuration Table expected to be generated
- *  by confdefs.h.
+ * This is the POSIX API Configuration Table expected to be generated
+ * by confdefs.h.
  */
 extern posix_api_configuration_table Configuration_POSIX_API;
 
diff --git a/cpukit/posix/include/rtems/posix/key.h b/cpukit/posix/include/rtems/posix/key.h
index edcaa42685..f0f039ec1d 100644
--- a/cpukit/posix/include/rtems/posix/key.h
+++ b/cpukit/posix/include/rtems/posix/key.h
@@ -1,5 +1,7 @@
 /**
- * @file rtems/posix/key.h
+ * @file
+ * 
+ * @brief POSIX Key Private Support
  *
  * This include file contains all the private support information for
  * POSIX key.
@@ -20,20 +22,22 @@
 #include <rtems/score/object.h>
 
 /**
- *  @defgroup POSIX_KEY Key
+ * @defgroup POSIX_KEY POSIX Key
  *
- *  @ingroup POSIX
+ * @ingroup POSIX
+ * 
+ * @{
  */
-/**@{*/
+
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 /**
- *  This is the data Structure used to manage a POSIX key.
+ * This is the data Structure used to manage a POSIX key.
  *
- *  @note The Values is a table indexed by the index portion of the
- *        ID of the currently executing thread.
+ * NOTE: The Values is a table indexed by the index portion of the
+ *       ID of the currently executing thread.
  */
 typedef struct {
    /** This field is the Object control structure. */
@@ -45,52 +49,53 @@ typedef struct {
 }  POSIX_Keys_Control;
 
 /**
- *  The following defines the information control block used to manage
- *  this class of objects.
+ * The following defines the information control block used to manage
+ * this class of objects.
  */
 POSIX_EXTERN Objects_Information  _POSIX_Keys_Information;
 
 /**
- *  @brief POSIX Keys Manager Initialization
+ * @brief POSIX keys manager initialization.
  *
- *  This routine performs the initialization necessary for this manager.
+ * This routine performs the initialization necessary for this manager.
  */
 void _POSIX_Key_Manager_initialization(void);
 
 /**
- *  @brief Thread-Specific Data Key Create
+ * @brief Create thread-specific data POSIX key.
  *
- *  This function executes all the destructors associated with the thread's
- *  keys.  This function will execute until all values have been set to NULL.
+ * This function executes all the destructors associated with the thread's
+ * keys.  This function will execute until all values have been set to NULL.
  *
- *  @param[in] thread is the thread whose keys should have all their
- *             destructors run.
+ * @param[in] thread is a pointer to the thread whose keys should have 
+ *            all their destructors run.
  *
- *  @note This is the routine executed when a thread exits to
- *        run through all the keys and do the destructor action.
+ * NOTE: This is the routine executed when a thread exits to
+ *       run through all the keys and do the destructor action.
  */
 void _POSIX_Keys_Run_destructors(
   Thread_Control *thread
 );
 
 /**
- *  @brief Free Key Memory
+ * @brief Free a POSIX key table memory.
  *
- *  This memory frees the key table memory associated with @a the_key.
+ * This memory frees the key table memory associated with @a the_key.
  *
- *  @param[in] the_key is the POSIX key to free the table memory of.
+ * @param[in] the_key is a pointer to the POSIX key to free
+ * the table memory of.
  */
 void _POSIX_Keys_Free_memory(
   POSIX_Keys_Control *the_key
 );
 
 /**
- *  @brief _POSIX_Keys_Free
+ * @brief Free a POSIX keys control block.
  *
- *  This routine frees a keys control block to the
- *  inactive chain of free keys control blocks.
+ * This routine frees a keys control block to the
+ * inactive chain of free keys control blocks.
  *
- *  @param[in] the_key is the POSIX key to free.
+ * @param[in] the_key is a pointer to the POSIX key to free.
  */
 RTEMS_INLINE_ROUTINE void _POSIX_Keys_Free (
   POSIX_Keys_Control *the_key
@@ -98,9 +103,11 @@ RTEMS_INLINE_ROUTINE void _POSIX_Keys_Free (
 
 #include <rtems/posix/key.inl>
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif
-/**@}*/
+
 #endif
 /*  end of include file */
diff --git a/cpukit/posix/include/rtems/posix/mqueue.h b/cpukit/posix/include/rtems/posix/mqueue.h
index 582d5b73b2..cef85e8045 100644
--- a/cpukit/posix/include/rtems/posix/mqueue.h
+++ b/cpukit/posix/include/rtems/posix/mqueue.h
@@ -1,20 +1,22 @@
 /**
- * @file rtems/posix/mqueue.h
+ * @file
+ * 
+ * @brief POSIX Message Queues Private Private Support
  *
  * 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.
+ * 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.
  */
 
 /*
@@ -36,19 +38,16 @@
 #include <rtems/posix/posixapi.h>
 
 /**
- *  @defgroup POSIX_MQUEUE_P Message Queues Private Support Information
+ *  @defgroup POSIX_MQUEUE_P Message Queues Private Support
  *
- *  @ingroup POSIX
+ *  @ingroup POSIX_MQUEUE
+ * 
+ * @{
  */
-/**@{*/
 #ifdef __cplusplus
 extern "C" {
 #endif
 
-/**
- *  @ingroup POSIX_MQUEUE
- */
-
 /*
  *  Data Structure used to manage a POSIX message queue
  */
@@ -78,24 +77,24 @@ typedef struct {
 POSIX_EXTERN Objects_Information  _POSIX_Message_queue_Information;
 POSIX_EXTERN Objects_Information  _POSIX_Message_queue_Information_fds;
 
-/*
- *  @brief Initializes message_queue Manager Related Data Structures
+/**
+ * @brief Initialize message_queue manager related data structures.
  *
- *  DESCRIPTION:
+ * DESCRIPTION:
  *
- *  This routine performs the initialization necessary for this manager.
+ * 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.]
+ * 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.
+ *        This code ignores the O_RDONLY/O_WRONLY/O_RDWR flag at open
+ *        time.
  *
  */
 
@@ -120,12 +119,12 @@ int _POSIX_Message_queue_Create_support(
 );
 
 /**
- *  @brief POSIX Delete Message Queue
+ * @brief Delete a POSIX message queue.
  *
- *  DESCRIPTION:
+ * DESCRIPTION:
  *
- *  This routine supports the mq_unlink and mq_close routines by
- *  doing most of the work involved with removing a message queue.
+ * 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
@@ -271,9 +270,11 @@ int _POSIX_Message_queue_Translate_core_message_queue_return_code(
 
 #include <rtems/posix/mqueue.inl>
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif
-/**@}*/
+
 #endif
 /*  end of include file */
diff --git a/cpukit/posix/include/rtems/posix/priority.h b/cpukit/posix/include/rtems/posix/priority.h
index a6a3c289da..1a12900057 100644
--- a/cpukit/posix/include/rtems/posix/priority.h
+++ b/cpukit/posix/include/rtems/posix/priority.h
@@ -1,5 +1,7 @@
 /**
- * @file rtems/posix/priority.h
+ * @file
+ * 
+ * @brief POSIX Priority Support
  *
  * This include file defines the interface to the POSIX priority
  * implementation.
@@ -23,25 +25,27 @@
  * @ingroup POSIX
  *
  * @brief Interface to the POSIX Priority Implementation
+ * 
+ * @{
  */
 
 #include <rtems/score/priority.h>
 
 /**
- *  1003.1b-1993,2.2.2.80 definition of priority, p. 19
+ * 1003.1b-1993,2.2.2.80 definition of priority, p. 19
  *
- *  "Numerically higher values represent higher priorities."
+ * "Numerically higher values represent higher priorities."
  *
- *  Thus, RTEMS Core has priorities run in the opposite sense of the POSIX API.
+ * Thus, RTEMS Core has priorities run in the opposite sense of the POSIX API.
  *
- *  There are only 254 posix priority levels since a task at priority level
- *  255 would never run because of the RTEMS idle task.  This is necessary
- *  because GNAT maps the lowest Ada task priority to the lowest thread
- *  priority.  The lowest priority Ada task should get to run, so there is
- *  a fundamental conflict with having 255 priorities.
+ * There are only 254 posix priority levels since a task at priority level
+ * 255 would never run because of the RTEMS idle task.  This is necessary
+ * because GNAT maps the lowest Ada task priority to the lowest thread
+ * priority.  The lowest priority Ada task should get to run, so there is
+ * a fundamental conflict with having 255 priorities.
  *
- *  But since RTEMS can be configured with fewer than 256 priorities,
- *  we use the internal constant.
+ * But since RTEMS can be configured with fewer than 256 priorities,
+ * we use the internal constant.
  */
 #define POSIX_SCHEDULER_MAXIMUM_PRIORITY (PRIORITY_MAXIMUM - 1)
 
@@ -52,46 +56,46 @@
 #define POSIX_SCHEDULER_MINIMUM_PRIORITY (1)
 
 /**
- *  @brief POSIX Is Priority Valid
+ * @brief Check if POSIX priority is valid.
  * 
- *  1003.1b-1993,2.2.2.80 definition of priority, p. 19
+ * 1003.1b-1993,2.2.2.80 definition of priority, p. 19
  *
- *  "Numerically higher values represent higher priorities."
+ * "Numerically higher values represent higher priorities."
  *
- *  Thus, RTEMS Core has priorities run in the opposite sense of the POSIX API.
+ * Thus, RTEMS Core has priorities run in the opposite sense of the POSIX API.
  *
- *  @param[in] priority is the priority to test
+ * @param[in] priority is the priority to test
  *
- *  @return This method returns true if the priority is valid and
- *          false otherwise.
+ * @retval TRUE The priority is valid.
+ * @retval FALSE The priority is invalid.
  */
 bool _POSIX_Priority_Is_valid(
   int priority
 );
 
 /**
- *  @brief Convert POSIX Priority To SuperCore Priority
+ * @brief Convert POSIX priority to SuperCore priority.
  *
- *  This method converts a POSIX API priority into onto the corresponding
- *  SuperCore value.
+ * This method converts a POSIX API priority into onto the corresponding
+ * SuperCore value.
  *
- *  @param[in] priority is the POSIX API priority.
+ * @param[in] priority is the POSIX API priority.
  *
- *  @return This method returns the corresponding SuperCore priority.
+ * @return This method returns the corresponding SuperCore priority.
  */
 RTEMS_INLINE_ROUTINE Priority_Control _POSIX_Priority_To_core(
   int priority
 );
 
 /**
- *  @brief Convert SuperCore Priority To POSIX Priority
+ * @brief Convert SuperCore priority To POSIX priority.
  *
- *  This method converts a SuperCore priority into onto the corresponding
- *  POSIX API value.
+ * This method converts a SuperCore priority into onto the corresponding
+ * POSIX API value.
  *
- *  @param[in] priority is the POSIX API priority.
+ * @param[in] priority is the POSIX API priority.
  *
- *  @return This method returns the corresponding POSIX priority.
+ * @return This method returns the corresponding POSIX priority.
  */
 RTEMS_INLINE_ROUTINE int _POSIX_Priority_From_core(
   Priority_Control priority
@@ -99,4 +103,6 @@ RTEMS_INLINE_ROUTINE int _POSIX_Priority_From_core(
 
 #include <rtems/posix/priority.inl>
 
+/** @} */
+
 #endif
diff --git a/cpukit/posix/include/rtems/posix/psignal.h b/cpukit/posix/include/rtems/posix/psignal.h
index 604b98982c..977fade2bb 100644
--- a/cpukit/posix/include/rtems/posix/psignal.h
+++ b/cpukit/posix/include/rtems/posix/psignal.h
@@ -1,5 +1,7 @@
 /**
- * @file rtems/posix/psignal.h
+ * @file
+ * 
+ * @brief Internal Information about POSIX Signals
  *
  * This include file defines internal information about POSIX signals.
  */
diff --git a/cpukit/posix/include/rtems/posix/psignalimpl.h b/cpukit/posix/include/rtems/posix/psignalimpl.h
index c416a7aa1b..d09722ddbf 100644
--- a/cpukit/posix/include/rtems/posix/psignalimpl.h
+++ b/cpukit/posix/include/rtems/posix/psignalimpl.h
@@ -1,5 +1,7 @@
 /**
- * @file rtems/posix/psignal.h
+ * @file
+ * 
+ * @brief POSIX Signals Support
  *
  * This include file defines internal information about POSIX signals.
  */
@@ -22,6 +24,8 @@
  * @ingroup POSIX
  *
  * @brief Internal Information about POSIX Signals
+ * 
+ * @{
  */
 
 #include <rtems/posix/psignal.h>
@@ -72,7 +76,7 @@ extern API_extensions_Post_switch_control _POSIX_signals_Post_switch;
  */
 
 /**
- *  @brief POSIX Signals Manager Initialization
+ * @brief POSIX signals manager initialization.
  */
 void _POSIX_signals_Manager_Initialization(void);
 
@@ -82,7 +86,7 @@ static inline void _POSIX_signals_Add_post_switch_extension(void)
 }
 
 /**
- * @brief POSIX Signals Thread Unlock
+ * @brief Unlock POSIX signals thread.
  *
  * XXX this routine could probably be cleaned up
  */
@@ -93,7 +97,7 @@ bool _POSIX_signals_Unblock_thread(
 );
 
 /**
- *  @brief POSIX Signals Check Signal
+ *  @brief Check POSIX signal.
  */
 bool _POSIX_signals_Check_signal(
   POSIX_API_Control  *api,
@@ -102,7 +106,7 @@ bool _POSIX_signals_Check_signal(
 );
 
 /**
- *  @brief POSIX Signals Clear Signals
+ * @brief Clear POSIX signals.
  */
 bool _POSIX_signals_Clear_signals(
   POSIX_API_Control  *api,
@@ -119,7 +123,7 @@ int killinfo(
 );
 
 /**
- *  @brief POSIX Signals Set Process Signals
+ *  @brief Set POSIX process signals.
  */
 void _POSIX_signals_Set_process_signals(
   sigset_t   mask
@@ -138,5 +142,7 @@ void _POSIX_signals_Clear_process_signals(
 
 void _POSIX_signals_Abnormal_termination_handler( int signo );
 
+/** @} */
+
 #endif
 /* end of file */
diff --git a/cpukit/posix/include/rtems/posix/pthread.h b/cpukit/posix/include/rtems/posix/pthread.h
index 5932d45a39..d0d2c2db5d 100644
--- a/cpukit/posix/include/rtems/posix/pthread.h
+++ b/cpukit/posix/include/rtems/posix/pthread.h
@@ -1,5 +1,7 @@
 /**
- * @file rtems/posix/pthread.h
+ * @file
+ * 
+ * @brief POSIX Threads Private Support
  *
  * This include file contains all the private support information for
  * POSIX threads.
@@ -21,12 +23,6 @@
 #include <rtems/posix/config.h>
 #include <rtems/posix/threadsup.h>
 
-/**
- *  @defgroup POSIX_PTHREADS Private Threads
- *
- *  @ingroup POSIX
- */
-/**@{*/
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -37,77 +33,79 @@ extern "C" {
  * @ingroup POSIX
  *
  * @brief Private Support Information for POSIX Threads
+ * 
+ * @{
  */
 
 /**
- *  The following sets the minimum stack size for POSIX threads.
+ * The following sets the minimum stack size for POSIX threads.
  */
 #define PTHREAD_MINIMUM_STACK_SIZE (_Stack_Minimum() * 2)
 
 /**
- *  The following defines the information control block used to manage
- *  this class of objects.
+ * The following defines the information control block used to manage
+ * this class of objects.
  */
 POSIX_EXTERN Objects_Information  _POSIX_Threads_Information;
 
 /**
- *  This variable contains the default POSIX Thread attributes.
+ * This variable contains the default POSIX Thread attributes.
  */
 extern const pthread_attr_t _POSIX_Threads_Default_attributes;
 
 /**
- *  When the user configures a set of POSIX API initialization threads,
- *  This variable will point to the method used to initialize them.
+ * When the user configures a set of POSIX API initialization threads,
+ * This variable will point to the method used to initialize them.
  *
- *  @note It is instantiated and initialized by confdefs.h based upon
- *        application requirements.
+ * NOTE: It is instantiated and initialized by confdefs.h based upon
+ *       application requirements.
  */
 extern void (*_POSIX_Threads_Initialize_user_threads_p)(void);
 
 /**
- *  @brief _POSIX_Threads_Manager_initialization
+ * @brief POSIX threads manager initialization.
  *
- *  This routine performs the initialization necessary for this manager.
+ * This routine performs the initialization necessary for this manager.
  */
 void _POSIX_Threads_Manager_initialization(void);
 
 /**
- *  @brief _POSIX_Threads_Allocate
+ * @brief Allocate POSIX thread control block.
  *
- *  This function allocates a pthread control block from
- *  the inactive chain of free pthread control blocks.
+ * This function allocates a pthread control block from
+ * the inactive chain of free pthread control blocks.
  *
- *  @return This method returns a newly allocated thread.
+ * @return This method returns a newly allocated thread.
  */
 RTEMS_INLINE_ROUTINE Thread_Control *_POSIX_Threads_Allocate( void );
 
 /**
- *  @brief _POSIX_Threads_Free
+ * @brief Free POSIX control block.
  *
- *  This routine frees a pthread control block to the
- *  inactive chain of free pthread control blocks.
+ * This routine frees a pthread control block to the
+ * inactive chain of free pthread control blocks.
  *
- *  @param[in] the_pthread is the thread to free
+ * @param[in] the_pthread is a pointer to the thread to free.
  */
 RTEMS_INLINE_ROUTINE void _POSIX_Threads_Free(
   Thread_Control *the_pthread
 );
 
 /**
- *  @brief _POSIX_Threads_Get
+ * @brief Map POSIX thread IDs to control blocks.
  *
- *  This function maps pthread IDs to pthread control blocks.
- *  If ID corresponds to a local pthread, then it returns
- *  the_pthread control pointer which maps to ID and location
- *  is set to OBJECTS_LOCAL.  if the pthread ID is global and
- *  resides on a remote node, then location is set to OBJECTS_REMOTE,
- *  and the_pthread is undefined.  Otherwise, location is set
- *  to OBJECTS_ERROR and the_pthread is undefined.
+ * This function maps pthread IDs to pthread control blocks.
+ * If ID corresponds to a local pthread, then it returns
+ * the_pthread control pointer which maps to ID and location
+ * is set to OBJECTS_LOCAL.  if the pthread ID is global and
+ * resides on a remote node, then location is set to OBJECTS_REMOTE,
+ * and the_pthread is undefined.  Otherwise, location is set
+ * to OBJECTS_ERROR and the_pthread is undefined.
  *
- *  @param[in] id is the id to lookup
- *  @param[in] location points to the returned location value
+ * @param[in] id is the id to lookup
+ * @param[in] location points to the returned location value
  *
- *  @return This methods returns a pointer to the corresponding Thread_Control.
+ * @return This methods returns a pointer to the corresponding Thread_Control.
  */
 RTEMS_INLINE_ROUTINE Thread_Control *_POSIX_Threads_Get(
   pthread_t          id,
@@ -115,43 +113,45 @@ RTEMS_INLINE_ROUTINE Thread_Control *_POSIX_Threads_Get(
 );
 
 /**
- *  @brief _POSIX_Threads_Is_null
+ * @brief Check if a POSIX thread control block is NULL.
  *
- *  This function returns TRUE if the_pthread is NULL and FALSE otherwise.
+ * This function returns @c TRUE if the_pthread is @c NULL and @c FALSE
+ * otherwise.
  *
- *  @param[in] the_pthread is the thread pointer to check.
+ * @param[in] the_pthread is a pointer to the POSIX thread control block 
+ * to check.
  *
- *  @return This method returns true if the thread pointer is null.
+ * @retval TRUE The thread control block is @c NULL.
+ * @retval FALSE The thread control block is not @c NULL.
  */
 RTEMS_INLINE_ROUTINE bool _POSIX_Threads_Is_null(
   Thread_Control *the_pthread
 );
 
 /**
- *  @brief _POSIX_Threads_Sporadic_budget_callout
+ * @brief POSIX threads sporadic budget callout.
  *
- *  This routine handles the sporadic scheduling algorithm.
+ * This routine handles the sporadic scheduling algorithm.
  *
- *  @param[in] the_thread is the thread whose budget has been exceeded.
+ * @param[in] the_thread is a pointer to the thread whose budget
+ * has been exceeded.
  */
 void _POSIX_Threads_Sporadic_budget_callout(
   Thread_Control *the_thread
 );
 
 /**
- *  _POSIX_Threads_Sporadic_budget_TSR
+ * This routine supports the sporadic scheduling algorithm.  It
+ * is scheduled to be executed at the end of each replenishment
+ * period.  In sporadic scheduling a thread will execute at a
+ * high priority for a user specified amount of CPU time.  When
+ * it exceeds that amount of CPU time, its priority is automatically
+ * lowered. This TSR is executed when it is time to replenish
+ * the thread's processor budget and raise its priority.
  *
- *  This routine supports the sporadic scheduling algorithm.  It
- *  is scheduled to be executed at the end of each replenishment
- *  period.  In sporadic scheduling a thread will execute at a
- *  high priority for a user specified amount of CPU time.  When
- *  it exceeds that amount of CPU time, its priority is automatically
- *  lowered. This TSR is executed when it is time to replenish
- *  the thread's processor budget and raise its priority.
- *
- *  @param[in] id is ignored
- *  @param[in] argument is a pointer to the Thread_Control structure
- *             for the thread being replenished.
+ * @param[in] id is ignored
+ * @param[in] argument is a pointer to the Thread_Control structure
+ *            for the thread being replenished.
  */
 void _POSIX_Threads_Sporadic_budget_TSR(
   Objects_Id      id,
@@ -159,17 +159,18 @@ void _POSIX_Threads_Sporadic_budget_TSR(
 );
 
 /**
- *  @brief Translate sched_param into SuperCore Terms
+ * @brief Translate sched_param into SuperCore terms.
  *
- *  This method translates the POSIX API sched_param into the corresponding
- *  SuperCore settings.
+ * This method translates the POSIX API sched_param into the corresponding
+ * SuperCore settings.
  *
- *  @param[in] policy is the POSIX scheduling policy
- *  @param[in] param points to the scheduling parameter structure
- *  @param[in] budget_algorithm points to the output CPU Budget algorithm
- *  @param[in] budget_callout points to the output CPU Callout
+ * @param[in] policy is the POSIX scheduling policy
+ * @param[in] param points to the scheduling parameter structure
+ * @param[in] budget_algorithm points to the output CPU Budget algorithm
+ * @param[in] budget_callout points to the output CPU Callout
  *
- *  @return This method returns 0 on success or a POSIX error code.
+ * @retval 0 Indicates success.
+ * @retval error_code POSIX error code indicating failure.
  */
 int _POSIX_Thread_Translate_sched_param(
   int                                  policy,
@@ -179,7 +180,7 @@ 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.
@@ -188,9 +189,11 @@ extern void _POSIX_Threads_Initialize_user_threads_body(void);
 
 #include <rtems/posix/pthread.inl>
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif
-/**@}*/
+
 #endif
 /*  end of include file */
diff --git a/cpukit/posix/include/rtems/posix/ptimer.h b/cpukit/posix/include/rtems/posix/ptimer.h
index 1b791cc915..50840ac5f6 100644
--- a/cpukit/posix/include/rtems/posix/ptimer.h
+++ b/cpukit/posix/include/rtems/posix/ptimer.h
@@ -1,5 +1,7 @@
 /**
- * @file rtems/posix/ptimer.h
+ * @file
+ * 
+ * @brief POSIX Timers Private Support
  *
  * This include file contains all the private support information for
  * POSIX timers.
@@ -21,11 +23,12 @@
 #define _RTEMS_POSIX_PTIMER_H
 
 /**
- *  @defgroup POSIX_PRIV_TIMERS Timers
+ * @defgroup POSIX_PRIV_TIMERS POSIX Timers
  *
- *  @ingroup POSIX
+ * @ingroup POSIX
+ * 
+ * @{
  */
-/**@{*/
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -89,16 +92,18 @@ int timer_gettime(
 );
 
 /**
- *  @brief Get Overrun Count for a POSIX Per-Process Timer
+ * @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.
+ * 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
+ * 14.2.4 Per-Process Timers, P1003.1b-1993, p. 267
  */
 int timer_getoverrun(
   timer_t   timerid
 );
-/**@}*/
+
+/** @} */
+
 #endif
diff --git a/cpukit/posix/include/rtems/posix/rwlock.h b/cpukit/posix/include/rtems/posix/rwlock.h
index 411384c2c6..57351be532 100644
--- a/cpukit/posix/include/rtems/posix/rwlock.h
+++ b/cpukit/posix/include/rtems/posix/rwlock.h
@@ -1,5 +1,7 @@
 /**
- * @file rtems/posix/rwlock.h
+ * @file
+ * 
+ * @brief Constants and Structures Associated with the POSIX RWLock Manager
  *
  * This include file contains all the constants and structures associated
  * with the POSIX RWLock Manager.
@@ -33,13 +35,15 @@ extern "C" {
  * @ingroup POSIX
  *
  * @brief Constants and Structures Associated with the POSIX RWLock Manager
+ * 
+ * @{
  */
 
 #include <rtems/score/object.h>
 #include <rtems/score/corerwlock.h>
 
 /**
- *  This type defines the control block used to manage each RWLock.
+ * This type defines the control block used to manage each RWLock.
  */
 
 typedef struct {
@@ -50,33 +54,38 @@ typedef struct {
 }   POSIX_RWLock_Control;
 
 /**
- *  The following defines the information control block used to manage
- *  this class of objects.
+ * The following defines the information control block used to manage
+ * this class of objects.
  */
 
 POSIX_EXTERN Objects_Information  _POSIX_RWLock_Information;
 
 /**
- *  @brief _POSIX_RWLock_Manager_initialization
- *
- *  This routine performs the initialization necessary for this manager.
+ * @brief POSIX RWLock manager initialization.
  *
- *  @param[in] maximum_rwlocks is the total number of RWLocks allowed to
- *             concurrently be active in the system.
+ * This routine performs the initialization necessary for this manager.
  */
 
 void _POSIX_RWLock_Manager_initialization(void);
 
 /**
- *  @brief POSIX RWLock Translate Core RWLock Return Code
+ * @brief POSIX translate core RWLock return code.
  *
- *  This routine translates SuperCore RWLock status codes into the
- *  corresponding POSIX ones.
+ * This routine translates SuperCore RWLock status codes into the
+ * corresponding POSIX ones.
  *
  *
- *  @param[in] the_RWLock_status is the SuperCore status.
+ * @param[in] the_RWLock_status is the SuperCore status.
  *
- *  @return the corresponding POSIX status
+ * @return the corresponding POSIX status
+ * @retval 0 The status indicates that the operation completed successfully.
+ * @retval EINVAL The status indicates that the thread was blocked waiting for
+ * an operation to complete and the RWLock was deleted.
+ * @retval EBUSY This status indicates that the RWLock was not 
+ * immediately available.
+ * @retval ETIMEDOUT This status indicates that the calling task was 
+ * willing to block but the operation was unable to complete within
+ * the time allotted because the resource never became available.
  */
 int _POSIX_RWLock_Translate_core_RWLock_return_code(
   CORE_RWLock_Status  the_RWLock_status
@@ -86,6 +95,8 @@ int _POSIX_RWLock_Translate_core_RWLock_return_code(
 #include <rtems/posix/rwlock.inl>
 #endif
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/cpukit/posix/include/rtems/posix/sigset.h b/cpukit/posix/include/rtems/posix/sigset.h
index b0dd61fe58..0dd218913c 100644
--- a/cpukit/posix/include/rtems/posix/sigset.h
+++ b/cpukit/posix/include/rtems/posix/sigset.h
@@ -1,5 +1,7 @@
 /**
- * @file rtems/posix/sigset.h
+ * @file
+ * 
+ * @brief POSIX Signal Sets Management Helper
  *
  * This file defines the interface to implementation helper for management
  * of POSIX Signal Sets.
diff --git a/cpukit/posix/include/rtems/posix/spinlock.h b/cpukit/posix/include/rtems/posix/spinlock.h
index 44061bd42c..a535c6bae6 100644
--- a/cpukit/posix/include/rtems/posix/spinlock.h
+++ b/cpukit/posix/include/rtems/posix/spinlock.h
@@ -1,5 +1,7 @@
 /**
- * @file rtems/posix/spinlock.h
+ * @file
+ * 
+ * @brief POSIX Spinlock Support
  *
  * This include file contains all the constants and structures associated
  * with the POSIX Spinlock Manager.
@@ -33,13 +35,15 @@ extern "C" {
  * @ingroup POSIX
  *
  * @brief Constants and Structures Associated with the POSIX Spinlock Manager
+ * 
+ * @{
  */
 
 #include <rtems/score/object.h>
 #include <rtems/score/corespinlock.h>
 
 /**
- *  This type defines the control block used to manage each spinlock.
+ * This type defines the control block used to manage each spinlock.
  */
 
 typedef struct {
@@ -50,33 +54,29 @@ typedef struct {
 }   POSIX_Spinlock_Control;
 
 /**
- *  The following defines the information control block used to manage
- *  this class of objects.
+ * The following defines the information control block used to manage
+ * this class of objects.
  */
 
 POSIX_EXTERN Objects_Information  _POSIX_Spinlock_Information;
 
 /**
- *  @brief _POSIX_Spinlock_Manager_initialization
+ * @brief POSIX spinlock manager initialization.
  *
- *  This routine performs the initialization necessary for this manager.
- *
- *  @param[in] maximum_spinlocks is the total number of spinlocks allowed to
- *             concurrently be active in the system.
+ * This routine performs the initialization necessary for this manager.
  */
 
 void _POSIX_Spinlock_Manager_initialization(void);
 
 /**
- *  @brief POSIX Spinlock Translate Core Spinlock Return Code
- *
- *  This routine translates SuperCore Spinlock status codes into the
- *  corresponding POSIX ones.
+ * @brief Translate core spinlock status code.
  *
+ * This routine translates SuperCore Spinlock status codes into the
+ * corresponding POSIX ones.
+ * 
+ * @param[in] the_spinlock_status is the SuperCore status.
  *
- *  @param[in] the_spinlock_status is the SuperCore status.
- *
- *  @return the corresponding POSIX status
+ * @return the corresponding POSIX status
  */
 int _POSIX_Spinlock_Translate_core_spinlock_return_code(
   CORE_spinlock_Status  the_spinlock_status
@@ -86,6 +86,8 @@ int _POSIX_Spinlock_Translate_core_spinlock_return_code(
 #include <rtems/posix/spinlock.inl>
 #endif
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/cpukit/posix/include/rtems/posix/threadsup.h b/cpukit/posix/include/rtems/posix/threadsup.h
index c5a2e3db7e..2d9c6adfa6 100644
--- a/cpukit/posix/include/rtems/posix/threadsup.h
+++ b/cpukit/posix/include/rtems/posix/threadsup.h
@@ -1,5 +1,7 @@
 /**
- * @file rtems/posix/threadsup.h
+ * @file
+ * 
+ * @brief POSIX Thread API Support
  *
  * This defines the POSIX thread API extension.
  */
@@ -24,15 +26,16 @@
  *  @defgroup POSIX_THREAD Thread API Extension
  *
  *  @ingroup POSIX
+ * 
+ * @{
  */
-/**@{*/
 #ifdef __cplusplus
 extern "C" {
 #endif
 
-/*!
- *  This defines the POSIX API support structure associated with
- *  each thread in a system with POSIX configured.
+/**
+ * This defines the POSIX API support structure associated with
+ * each thread in a system with POSIX configured.
  */
 typedef struct {
   /** This is the POSIX threads attribute set. */
@@ -46,13 +49,13 @@ typedef struct {
   /** This is the thread's current set of scheduling parameters. */
   struct sched_param      schedparam;
   /**
-   *  This is the high priority to execute at when using the sporadic
-   *  scheduler.
+   * This is the high priority to execute at when using the sporadic
+   * scheduler.
    */
   int                     ss_high_priority;
   /**
-   *  This is the timer which controls when the thread executes at
-   *  high and low priority when using the sporadic scheduler.
+   * This is the timer which controls when the thread executes at
+   * high and low priority when using the sporadic scheduler.
    */
   Watchdog_Control        Sporadic_timer;
 
@@ -78,19 +81,19 @@ typedef struct {
 
 } POSIX_API_Control;
 
-/*!
- *  @brief POSIX Thread Exit Shared Helper
+/**
+ * @brief POSIX thread exit shared helper.
  *
- *  16.1.5.1 Thread Termination, p1003.1c/Draft 10, p. 150
+ * 16.1.5.1 Thread Termination, p1003.1c/Draft 10, p. 150
  *
- *  This method is a helper routine which ensures that all
- *  POSIX thread calls which result in a thread exiting will
- *  do so in the same manner.
+ * This method is a helper routine which ensures that all
+ * POSIX thread calls which result in a thread exiting will
+ * do so in the same manner.
  *
- *  @param[in] the_thread is the thread exiting or being canceled
- *  @param[in] value_ptr is the value to be returned by the thread
+ * @param[in] the_thread is a pointer to the thread exiting or being canceled
+ * @param[in] value_ptr is a pointer the value to be returned by the thread
  *
- *  NOTE: Key destructors are executed in the POSIX api delete extension.
+ * NOTE: Key destructors are executed in the POSIX api delete extension.
  *
  */
 void _POSIX_Thread_Exit(
@@ -98,9 +101,11 @@ void _POSIX_Thread_Exit(
   void           *value_ptr
 );
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif
-/**@}*/
+
 #endif
 /* end of include file */
diff --git a/cpukit/posix/include/rtems/posix/time.h b/cpukit/posix/include/rtems/posix/time.h
index d0dc4a27fe..d00fc02491 100644
--- a/cpukit/posix/include/rtems/posix/time.h
+++ b/cpukit/posix/include/rtems/posix/time.h
@@ -1,5 +1,7 @@
 /**
- * @file rtems/posix/time.h
+ * @file
+ * 
+ * @brief POSIX Time Types
  *
  * This defines the interface to implementation helper routines related
  * to POSIX time types.
@@ -20,18 +22,19 @@
 #include <rtems/score/timespec.h>
 #include <rtems/score/watchdog.h>
 /**
- *  @defgroup POSIX_TIMETYPES Time Types
+ * @defgroup POSIX_TIMETYPES POSIX Time Types
  *
- *  @ingroup POSIX
+ * @ingroup POSIX
+ * 
+ * @{
  */
-/**@{*/
 
 /**
- *  @brief Absolute Timeout Conversion Results
+ * @brief Absolute timeout conversion results.
  *
- *  This enumeration defines the possible results of converting
- *  an absolute time used for timeouts to POSIX blocking calls to
- *  a number of ticks.
+ * This enumeration defines the possible results of converting
+ * an absolute time used for timeouts to POSIX blocking calls to
+ * a number of ticks.
  */
 typedef enum {
   /** The timeout is invalid. */
@@ -45,24 +48,25 @@ typedef enum {
 } POSIX_Absolute_timeout_conversion_results_t;
 
 /**
- *  @brief Convert Absolute Timeout to Ticks
+ * @brief Convert absolute timeout to ticks.
  *
- *  This method takes an absolute time being used as a timeout
- *  to a blocking directive, validates it and returns the number
- *  of corresponding clock ticks for use by the SuperCore.
+ * This method takes an absolute time being used as a timeout
+ * to a blocking directive, validates it and returns the number
+ * of corresponding clock ticks for use by the SuperCore.
  *
- *  @param[in] abstime is the timeout
- *  @param[in] ticks_out will contain the number of ticks
+ * @param[in] abstime is a pointer to the timeout
+ * @param[out] ticks_out will contain the number of ticks
  *
- *  @return This method returns the number of ticks in @a ticks_out
- *          and a status value indicating whether the absolute time
- *          is valid, in the past, equal to the current time or in
- *          the future as it should be.
+ * @return This method returns the number of ticks in @a ticks_out
+ *         and a status value indicating whether the absolute time
+ *         is valid, in the past, equal to the current time or in
+ *         the future as it should be.
  */
 POSIX_Absolute_timeout_conversion_results_t _POSIX_Absolute_timeout_to_ticks(
   const struct timespec *abstime,
   Watchdog_Interval     *ticks_out
 );
 
+/** @} */
+
 #endif
-/**@}*/
diff --git a/cpukit/posix/include/rtems/posix/timer.h b/cpukit/posix/include/rtems/posix/timer.h
index 1298178e95..544acd712a 100644
--- a/cpukit/posix/include/rtems/posix/timer.h
+++ b/cpukit/posix/include/rtems/posix/timer.h
@@ -1,5 +1,7 @@
 /**
- * @file rtems/posix/timer.h
+ * @file 
+ * 
+ * @brief POSIX Timers Internal Support
  *
  * This include files defines the internal support for implementation of
  * POSIX Timers.
@@ -22,11 +24,13 @@
 #include <rtems/score/watchdog.h> /* Watchdog_Control */
 
 /**
- *  @defgroup POSIX_INTERNAL_TIMERS Timers
+ * @defgroup POSIX_INTERNAL_TIMERS Timers
  *
- *  @ingroup POSIX
+ * @ingroup POSIX
+ * 
+ * @{
  */
-/**@{*/
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -108,9 +112,11 @@ POSIX_EXTERN Objects_Information  _POSIX_Timer_Information;
 #include <rtems/posix/timer.inl>
 #endif
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif
-/**@}*/
+
 #endif
 /* end of include file */