posix: Doxygen Clean Up Task #2

4 files changed, 76 insertions, 60 deletions

diff --git a/cpukit/posix/include/rtems/posix/mutex.h b/cpukit/posix/include/rtems/posix/mutex.h
index 727745ae67..f44a1c64b1 100644
--- a/cpukit/posix/include/rtems/posix/mutex.h
+++ b/cpukit/posix/include/rtems/posix/mutex.h
@@ -1,5 +1,7 @@
 /**
- * @file rtems/posix/mutex.h
+ * @file
+ * 
+ * @brief POSIX MUTEX Support
  *
  * This include file contains all the private support information for
  * POSIX mutex's.
@@ -27,6 +29,8 @@ extern "C" {
  * @ingroup POSIX
  *
  * @brief Private Support Information for POSIX Mutex
+ * 
+ * @{
  */
 
 #include <rtems/score/coremutex.h>
@@ -138,16 +142,28 @@ int _POSIX_Mutex_Lock_support(
 );
 
 /**
- *  @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
+ * @brief Convert core mutex status codes into the appropriate POSIX status
+ * values.
+ *
+ * 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
+ *
+ * @retval 0 Mutex status code indicates the operation completed successfully.
+ * @retval EBUSY Mutex status code indicates that the operation unable to 
+ * complete immediately because the resource was unavailable.
+ * @retval EDEADLK Mutex status code indicates that an attempt was made to
+ * relock a mutex for which nesting is not configured.
+ * @retval EPERM Mutex status code indicates that an attempt was made to 
+ * release a mutex by a thread other than the thread which locked it.
+ * @retval EINVAL Mutex status code indicates that the thread was blocked
+ * waiting for an operation to complete and the mutex was deleted.
+ * @retval ETIMEDOUT Mutex status code 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_Mutex_Translate_core_mutex_return_code(
@@ -198,5 +214,7 @@ POSIX_Mutex_Control *_POSIX_Mutex_Get_interrupt_disable (
 }
 #endif
 
+/** @} */
+
 #endif
 /*  end of include file */
diff --git a/cpukit/posix/include/rtems/posix/posixapi.h b/cpukit/posix/include/rtems/posix/posixapi.h
index dd8f8c2873..7092d1eddf 100644
--- a/cpukit/posix/include/rtems/posix/posixapi.h
+++ b/cpukit/posix/include/rtems/posix/posixapi.h
@@ -1,5 +1,7 @@
 /**
- * @file rtems/posix/posixapi.h
+ * @file
+ * 
+ * @brief POSIX API Implementation
  *
  * This include file defines the top level interface to the POSIX API
  * implementation in RTEMS.
@@ -29,27 +31,27 @@
  */
 
 /**
- *  @brief Initialize POSIX API
+ * @brief Initialize POSIX API.
  *
- *  This method is responsible for initializing each of the POSIX
- *  API managers.
+ * This method is responsible for initializing each of the POSIX
+ * API managers.
  */
 void _POSIX_API_Initialize(void);
 
 /**
- *  @brief Queries the object identifier @a id for a @a name.
+ * @brief Queries the object identifier @a id for a @a name.
  *
- *  @param[in] information Object information.
- *  @param[in] name Zero terminated name string to look up.
- *  @param[out] id Pointer for identifier.  The pointer must be valid.
- *  @param[out] len Pointer for string length.  The pointer must be valid.
+ * @param[in] information Object information.
+ * @param[in] name Zero terminated name string to look up.
+ * @param[out] id Pointer for identifier.  The pointer must be valid.
+ * @param[out] len Pointer for string length.  The pointer must be valid.
  *
- *  @retval 0 Successful operation.
- *  @retval EINVAL The @a name pointer is @c NULL or the @a name string has
- *  zero length.
- *  @retval ENAMETOOLONG The @a name string length is greater than or equal to
- *  @c NAME_MAX.
- *  @retval ENOENT Found no corresponding identifier.
+ * @retval 0 Successful operation.
+ * @retval EINVAL The @a name pointer is @c NULL or the @a name string has
+ * zero length.
+ * @retval ENAMETOOLONG The @a name string length is greater than or equal to
+ * @c NAME_MAX.
+ * @retval ENOENT Found no corresponding identifier.
  */
 int _POSIX_Name_to_id(
   Objects_Information *information,
@@ -58,7 +60,7 @@ int _POSIX_Name_to_id(
   size_t              *len
 );
 
-/**@}*/
+/** @} */
 
 #endif
 /* end of include file */
diff --git a/cpukit/posix/include/rtems/posix/semaphore.h b/cpukit/posix/include/rtems/posix/semaphore.h
index d7263b3e72..031a511d70 100644
--- a/cpukit/posix/include/rtems/posix/semaphore.h
+++ b/cpukit/posix/include/rtems/posix/semaphore.h
@@ -1,5 +1,5 @@
 /**
- * @file rtems/posix/semaphore.h
+ * @file
  *
  * @brief Private Support Information for POSIX Semaphores
  *
@@ -20,19 +20,14 @@
 #define _RTEMS_POSIX_SEMAPHORE_H
 
 /**
- *  @defgroup POSIX_SEMAPHORES Semaphore
- *
- *  @ingroup POSIX
+ * @addtogroup POSIX_SEMAPHORES
+ * 
+ * @{
  */
-/**@{*/
 #ifdef __cplusplus
 extern "C" {
 #endif
 
-/**
- * @ingroup POSIX_SEMAPHORE
- */
-
 #include <semaphore.h>
 #include <rtems/score/coresem.h>
 #include <rtems/posix/posixapi.h>
@@ -147,25 +142,24 @@ int _POSIX_Semaphore_Create_support(
 );
 
 /**
- *  @brief POSIX Delete Semaphore
+ * @brief POSIX delete a semaphore. 
  *
- *  DESCRIPTION:
+ * DESCRIPTION:
  *
- *  This routine supports the sem_close and sem_unlink routines.
+ * This routine supports the sem_close and sem_unlink routines.
  */
 void _POSIX_Semaphore_Delete(
   POSIX_Semaphore_Control *the_semaphore
 );
 
-/*
- *  @brief POSIX Semaphore Wait Support
+/**
+ * @brief POSIX semaphore wait support.
  *
- *  DESCRIPTION:
+ * DESCRIPTION:
  *
- *  This routine supports the sem_wait, sem_trywait, and sem_timedwait
- *  services.
+ * This routine supports the sem_wait, sem_trywait, and sem_timedwait
+ * services.
  */
-
 int _POSIX_Semaphore_Wait_support(
   sem_t               *sem,
   bool                 blocking,
@@ -191,7 +185,7 @@ int _POSIX_Semaphore_Translate_core_semaphore_return_code(
 }
 #endif
 
-/**@}*/
+/** @} */
 
 #endif
 /*  end of include file */
diff --git a/cpukit/posix/include/semaphore.h b/cpukit/posix/include/semaphore.h
index 37e3fd54b4..65708c96f1 100644
--- a/cpukit/posix/include/semaphore.h
+++ b/cpukit/posix/include/semaphore.h
@@ -1,5 +1,7 @@
 /**
- * @file semaphore.h
+ * @file
+ * 
+ * @brief Private Support Information for POSIX Semaphores
  *
  * This file contains definitions that are internal to the RTEMS
  * implementation of POSIX Semaphores.
@@ -55,9 +57,9 @@ int sem_init(
 );
 
 /**
- *  @brief Destroy an Unnamed Semaphore
+ * @brief Destroy an unnamed semaphore.
  *
- *  11.2.2 Destroy an Unnamed Semaphore, P1003.1b-1993, p.220
+ * 11.2.2 Destroy an Unnamed Semaphore, P1003.1b-1993, p.220
  */
 int sem_destroy(
   sem_t *sem
@@ -75,7 +77,7 @@ sem_t *sem_open(
 );
 
 /**
- * @brief Close a Named Semaphore
+ * @brief Close a named semaphore.
  *
  * Routine to close a semaphore that has been opened or initialized.
  *
@@ -86,7 +88,7 @@ int sem_close(
 );
 
 /**
- * @brief Remove a Named Semaphore
+ * @brief Remove a named semaphore.
  *
  * Unlinks a named semaphore, sem_close must also be called to remove
  * the semaphore.
@@ -98,20 +100,20 @@ int sem_unlink(
 );
 
 /**
- *  @brief Lock a Semaphore
+ * @brief Lock a semaphore.
  *
- *  11.2.6 Lock a Semaphore, P1003.1b-1993, p.226
+ * 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
 );
 
 /**
- *  @brief Lock a Semaphore
+ * @brief Lock a semaphore.
  *
- *  @see sem_wait()
+ * @see sem_wait()
  */
 int sem_trywait(
   sem_t *sem
@@ -119,7 +121,7 @@ int sem_trywait(
 
 #if defined(_POSIX_TIMEOUTS)
 /**
- *  @brief Lock a Semaphore
+ * @brief Lock a semaphore.
  */
 int sem_timedwait(
   sem_t                 *sem,
@@ -128,16 +130,16 @@ int sem_timedwait(
 #endif
 
 /**
- *  @brief Unlock a Semaphore
+ * @brief Unlock a semaphore.
  *
- *  11.2.7 Unlock a Semaphore, P1003.1b-1993, p.227
+ * 11.2.7 Unlock a Semaphore, P1003.1b-1993, p.227
  */
 int sem_post(
   sem_t  *sem
 );
 
 /**
- * @brief Get the Value of a Semaphore
+ * @brief Get the value of a semaphore.
  *
  * 11.2.8 Get the Value of a Semaphore, P1003.1b-1993, p.229
  */