posix: Doxygen Clean Up Task #1

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
  * 
  * @param[in] filedes is the file descriptor
- *  @param[in] aiocbp is the asynchronous I/O control block
+ * @param[in] aiocbp is a pointer to the asynchronous I/O control block
  * 
- *  @return This method returns AIO_CANCELED if the requested operation(s)
+ * @retval AIO_CANCELED The requested operation(s) were canceled. 
- *          were canceled. Otherwise, AIO_NOTCANCELED is returned indicating
+ * @retval AIO_NOTCANCELED Some of the requested operation(s) cannot be
- *          that at least one of the requested operation(s) cannot be canceled
+ * 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

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
+ * 
+ * @{
  */
-/**@{*/
 
 #ifdef __cplusplus
 extern "C" {
@@ -58,7 +59,7 @@ extern "C" {
 /**
  * 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;
 
@@ -93,7 +94,7 @@ int mq_close(
 );
 
 /**
- *  @brief Remove a Message Queue
+ * @brief Remove a message queue.
  *
  * 15.2.2 Remove a Message Queue, P1003.1b-1993, p. 276
  *
@@ -116,7 +117,7 @@ int mq_unlink(
 /**
  * 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
+ * @see mq_send()
- *
- *  @note P1003.4b/D8, p. 45 adds mq_timedsend().
  */
 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
  *
- *  @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 */

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.
  */

cpukit/posix/include/rtems/posix/barrier.h

@@ -1,5 +1,7 @@
 /**
- * @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.
@@ -30,8 +32,9 @@
  *
  * This encapsulates functionality which implements the RTEMS API
  * Barrier Manager.
+ * 
+ * @{
  */
-/**@{*/
 
 #ifdef __cplusplus
 extern "C" {
@@ -59,23 +62,19 @@ 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.
  */
 
 void _POSIX_Barrier_Manager_initialization(void);
 
 /**
- *  @brief _POSIX_Barrier_Translate_core_barrier_return_code (
+ * @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.
  *
  * @return the corresponding POSIX 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 */

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.
@@ -32,12 +34,12 @@ 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.
  *
- *  @param[in] the_thread is the thread whose cancelation handlers
+ * @param[in] the_thread is a pointer to the thread whose cancelation handlers
  *            should be run
  */
 void _POSIX_Threads_cancel_run(
@@ -45,12 +47,12 @@ void _POSIX_Threads_cancel_run(
 );
 
 /**
- *  @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.
  *
- *  @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

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
+ * 
+ * @{
  */
-/**@{*/
 #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
+ * @brief Implements wake up version of the "signal" operation.
- *
- *  _POSIX_Condition_variables_Signal_support
  * 
  * DESCRIPTION:
  *
  * 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 */

cpukit/posix/include/rtems/posix/config.h

@@ -1,5 +1,7 @@
 /**
- * @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,7 +62,7 @@ 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.

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,11 +22,13 @@
 #include <rtems/score/object.h>
 
 /**
- *  @defgroup POSIX_KEY Key
+ * @defgroup POSIX_KEY POSIX Key
  *
  * @ingroup POSIX
+ * 
+ * @{
  */
-/**@{*/
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -32,7 +36,7 @@ extern "C" {
 /**
  * This is the data Structure used to manage a POSIX key.
  *
- *  @note The Values is a table indexed by the index portion of the
+ * NOTE: The Values is a table indexed by the index portion of the
  *       ID of the currently executing thread.
  */
 typedef struct {
@@ -51,22 +55,22 @@ typedef struct {
 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.
  */
 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.
  *
- *  @param[in] thread is the thread whose keys should have all their
+ * @param[in] thread is a pointer to the thread whose keys should have 
- *             destructors run.
+ *            all their destructors run.
  *
- *  @note This is the routine executed when a thread exits to
+ * 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(
@@ -74,23 +78,24 @@ void _POSIX_Keys_Run_destructors(
 );
 
 /**
- *  @brief Free Key Memory
+ * @brief Free a POSIX key table memory.
  *
  * 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.
  *
- *  @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 */

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

@@ -1,5 +1,7 @@
 /**
- * @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.
@@ -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,8 +77,8 @@ 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:
  *
@@ -120,7 +119,7 @@ int _POSIX_Message_queue_Create_support(
 );
 
 /**
- *  @brief POSIX Delete Message Queue
+ * @brief Delete a POSIX message queue.
  *
  * DESCRIPTION:
  *
@@ -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 */

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,6 +25,8 @@
  * @ingroup POSIX
  *
  * @brief Interface to the POSIX Priority Implementation
+ * 
+ * @{
  */
 
 #include <rtems/score/priority.h>
@@ -52,7 +56,7 @@
 #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
  *
@@ -62,15 +66,15 @@
  *
  * @param[in] priority is the priority to test
  *
- *  @return This method returns true if the priority is valid and
+ * @retval TRUE The priority is valid.
- *          false otherwise.
+ * @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.
@@ -84,7 +88,7 @@ RTEMS_INLINE_ROUTINE Priority_Control _POSIX_Priority_To_core(
 );
 
 /**
- *  @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.
@@ -99,4 +103,6 @@ RTEMS_INLINE_ROUTINE int _POSIX_Priority_From_core(
 
 #include <rtems/posix/priority.inl>
 
+/** @} */
+
 #endif

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.
  */

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 */

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,6 +33,8 @@ extern "C" {
  * @ingroup POSIX
  *
  * @brief Private Support Information for POSIX Threads
+ * 
+ * @{
  */
 
 /**
@@ -59,20 +57,20 @@ 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.
  *
- *  @note It is instantiated and initialized by confdefs.h based upon
+ * 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.
  */
 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.
@@ -82,19 +80,19 @@ void _POSIX_Threads_Manager_initialization(void);
 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.
  *
- *  @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
@@ -115,32 +113,34 @@ 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.
  *
- *  @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
@@ -159,7 +159,7 @@ 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.
@@ -169,7 +169,8 @@ void _POSIX_Threads_Sporadic_budget_TSR(
  * @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 */

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
+ * 
+ * @{
  */
-/**@{*/
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -89,7 +92,7 @@ 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
@@ -100,5 +103,7 @@ int timer_gettime(
 int timer_getoverrun(
   timer_t   timerid
 );
-/**@}*/
+
+/** @} */
+
 #endif

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,6 +35,8 @@ extern "C" {
  * @ingroup POSIX
  *
  * @brief Constants and Structures Associated with the POSIX RWLock Manager
+ * 
+ * @{
  */
 
 #include <rtems/score/object.h>
@@ -57,18 +61,15 @@ typedef struct {
 POSIX_EXTERN Objects_Information  _POSIX_RWLock_Information;
 
 /**
- *  @brief _POSIX_RWLock_Manager_initialization
+ * @brief POSIX RWLock manager initialization.
  *
  * This routine performs the initialization necessary for this manager.
- *
- *  @param[in] maximum_rwlocks is the total number of RWLocks allowed to
- *             concurrently be active in the system.
  */
 
 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.
@@ -77,6 +78,14 @@ void _POSIX_RWLock_Manager_initialization(void);
  * @param[in] the_RWLock_status is the SuperCore 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

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.

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,6 +35,8 @@ extern "C" {
  * @ingroup POSIX
  *
  * @brief Constants and Structures Associated with the POSIX Spinlock Manager
+ * 
+ * @{
  */
 
 #include <rtems/score/object.h>
@@ -57,23 +61,19 @@ typedef struct {
 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.
  */
 
 void _POSIX_Spinlock_Manager_initialization(void);
 
 /**
- *  @brief POSIX Spinlock Translate Core Spinlock Return Code
+ * @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.
  *
  * @return the corresponding POSIX status
@@ -86,6 +86,8 @@ int _POSIX_Spinlock_Translate_core_spinlock_return_code(
 #include <rtems/posix/spinlock.inl>
 #endif
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif

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,13 +26,14 @@
  *  @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.
  */
@@ -78,8 +81,8 @@ 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
  *
@@ -87,8 +90,8 @@ typedef struct {
  * 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] the_thread is a pointer to the thread exiting or being canceled
- *  @param[in] value_ptr is the value to be returned by the thread
+ * @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.
  *
@@ -98,9 +101,11 @@ void _POSIX_Thread_Exit(
   void           *value_ptr
 );
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif
-/**@}*/
+
 #endif
 /* end of include file */

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,14 +22,15 @@
 #include <rtems/score/timespec.h>
 #include <rtems/score/watchdog.h>
 /**
- *  @defgroup POSIX_TIMETYPES Time Types
+ * @defgroup POSIX_TIMETYPES POSIX Time Types
  *
  * @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
@@ -45,14 +48,14 @@ 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.
  *
- *  @param[in] abstime is the timeout
+ * @param[in] abstime is a pointer to the timeout
- *  @param[in] ticks_out will contain the number of ticks
+ * @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
@@ -64,5 +67,6 @@ POSIX_Absolute_timeout_conversion_results_t _POSIX_Absolute_timeout_to_ticks(
   Watchdog_Interval     *ticks_out
 );
 
+/** @} */
+
 #endif
-/**@}*/

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.
@@ -25,8 +27,10 @@
  * @defgroup POSIX_INTERNAL_TIMERS Timers
  *
  * @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 */