muteximpl.h: Comment clean up

1 files changed, 44 insertions, 108 deletions

diff --git a/cpukit/posix/include/rtems/posix/muteximpl.h b/cpukit/posix/include/rtems/posix/muteximpl.h
index 29e93c2af5..710af7b6c8 100644
--- a/cpukit/posix/include/rtems/posix/muteximpl.h
+++ b/cpukit/posix/include/rtems/posix/muteximpl.h
@@ -7,7 +7,7 @@
  * inlined routines for POSIX mutex's.
  */
 
-/*  COPYRIGHT (c) 1989-2011.
+/*  COPYRIGHT (c) 1989-2013.
  *  On-Line Applications Research Corporation (OAR).
  *
  *  The license and distribution terms for this file may be
@@ -27,97 +27,61 @@
 extern "C" {
 #endif
 
-/*
+/**
  *  The following defines the information control block used to manage
  *  this class of objects.
  */
-
 POSIX_EXTERN Objects_Information  _POSIX_Mutex_Information;
 
-/*
+/**
  *  The default mutex attributes structure.
  */
-
 POSIX_EXTERN pthread_mutexattr_t _POSIX_Mutex_Default_attributes;
 
+/**
+ *  This array contains a mapping from Score Mutex return codes to
+ *  POSIX return codes.
+ */
 extern const int _POSIX_Mutex_Return_codes[CORE_MUTEX_STATUS_LAST + 1];
 
-/*
+/**
  *  @brief POSIX Mutex Manager Initialization
  *
- *  DESCRIPTION:
- *
  *  This routine performs the initialization necessary for this manager.
  */
-
 void _POSIX_Mutex_Manager_initialization(void);
 
-/*
- *  _POSIX_Mutex_Allocate
- *
- *  DESCRIPTION:
+/**
+ *  @brief POSIX Mutex Allocate
  *
  *  This function allocates a mutexes control block from
  *  the inactive chain of free mutexes control blocks.
  */
+RTEMS_INLINE_ROUTINE POSIX_Mutex_Control *_POSIX_Mutex_Allocate( void )
+{
+  return (POSIX_Mutex_Control *) _Objects_Allocate( &_POSIX_Mutex_Information );
+}
 
-RTEMS_INLINE_ROUTINE POSIX_Mutex_Control *_POSIX_Mutex_Allocate( void );
-
-/*
- *  _POSIX_Mutex_Free
- *
- *  DESCRIPTION:
+/**
+ *  @brief POSIX Mutex Free
  *
  *  This routine frees a mutexes control block to the
  *  inactive chain of free mutexes control blocks.
  */
-
-RTEMS_INLINE_ROUTINE void _POSIX_Mutex_Free (
+RTEMS_INLINE_ROUTINE void _POSIX_Mutex_Free(
   POSIX_Mutex_Control *the_mutex
-);
-
-#if 0
-/*
- *  _POSIX_Mutex_Get
- *
- *  DESCRIPTION:
- *
- *  This function maps mutexes IDs to mutexes control blocks.
- *  If ID corresponds to a local mutexes, then it returns
- *  the_mutex control pointer which maps to ID and location
- *  is set to OBJECTS_LOCAL.  if the mutexes ID is global and
- *  resides on a remote node, then location is set to OBJECTS_REMOTE,
- *  and the_mutex is undefined.  Otherwise, location is set
- *  to OBJECTS_ERROR and the_mutex is undefined.
- */
-
-RTEMS_INLINE_ROUTINE POSIX_Mutex_Control *_POSIX_Mutex_Get (
-  Objects_Id        *id,
-  Objects_Locations *location
-);
+)
+{
+  _Objects_Free( &_POSIX_Mutex_Information, &the_mutex->Object );
+}
 
-/*
- *  _POSIX_Mutex_Is_null
- *
- *  DESCRIPTION:
- *
- *  This function returns TRUE if the_mutex is NULL and FALSE otherwise.
- */
 
-RTEMS_INLINE_ROUTINE bool    _POSIX_Mutex_Is_null (
-  POSIX_Mutex_Control *the_mutex
-);
-#endif
-
-/*
- *  _POSIX_Mutex_Lock_support
- *
- *  DESCRIPTION:
+/**
+ *  @brief POSIX Mutex Lock Support Method
  *
  *  A support routine which implements guts of the blocking, non-blocking, and
  *  timed wait version of mutex lock.
  */
-
 int _POSIX_Mutex_Lock_support(
   pthread_mutex_t           *mutex,
   bool                       blocking,
@@ -125,10 +89,7 @@ int _POSIX_Mutex_Lock_support(
 );
 
 /**
- * @brief Convert core mutex status codes into the appropriate POSIX status
- * values.
- *
- * DESCRIPTION:
+ * @brief Convert Score mutex status codes into POSIX status values
  *
  * A support routine which converts core mutex status codes into the
  * appropriate POSIX status values.
@@ -137,16 +98,17 @@ int _POSIX_Mutex_Lock_support(
  *
  * @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.
+ *         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.
+ *         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.
+ *         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.
+ *         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.
+ *         willing to block but the operation was unable to complete
+ *         within the time allotted because the resource never became
+ *         available.
  */
 RTEMS_INLINE_ROUTINE int _POSIX_Mutex_Translate_core_mutex_return_code(
   CORE_mutex_Status  the_mutex_status
@@ -162,67 +124,41 @@ RTEMS_INLINE_ROUTINE int _POSIX_Mutex_Translate_core_mutex_return_code(
   return _POSIX_Mutex_Return_codes[the_mutex_status];
 }
 
-/*
- *  _POSIX_Mutex_Get
- *
- *  DESCRIPTION:
+/**
+ *  @brief POSIX Mutex Get (Thread Dispatch Disable)
  *
  *  A support routine which translates the mutex id into a local pointer.
  *  As a side-effect, it may create the mutex.
  *
- *  NOTE:
- *
- *  This version of the method uses a dispatching critical section.
+ *  @note This version of the method uses a dispatching critical section.
  */
-
 POSIX_Mutex_Control *_POSIX_Mutex_Get (
   pthread_mutex_t   *mutex,
   Objects_Locations *location
 );
 
-/*
- *  _POSIX_Mutex_Get
- *
- *  DESCRIPTION:
+/**
+ *  @brief POSIX Mutex Get (Interrupt Disable)
  *
  *  A support routine which translates the mutex id into a local pointer.
  *  As a side-effect, it may create the mutex.
  *
- *  NOTE:
- *
- *  This version of the method uses an interrupt critical section.
+ *  @note: This version of the method uses an interrupt critical section.
  */
-
 POSIX_Mutex_Control *_POSIX_Mutex_Get_interrupt_disable (
   pthread_mutex_t   *mutex,
   Objects_Locations *location,
   ISR_Level         *level
 );
  
-/*
- *  _POSIX_Mutex_Allocate
- */
- 
-RTEMS_INLINE_ROUTINE POSIX_Mutex_Control *_POSIX_Mutex_Allocate( void )
-{
-  return (POSIX_Mutex_Control *) _Objects_Allocate( &_POSIX_Mutex_Information );
-}
- 
-/*
- *  _POSIX_Mutex_Free
- */
- 
-RTEMS_INLINE_ROUTINE void _POSIX_Mutex_Free (
-  POSIX_Mutex_Control *the_mutex
-)
-{
-  _Objects_Free( &_POSIX_Mutex_Information, &the_mutex->Object );
-}
- 
-/*
- *  _POSIX_Mutex_Is_null
+/**
+ *  @brief POSIX Mutex Is NULL
+ *
+ *  This method is used to determine if a pointer to a POSIX mutex is NULL.
+ *
+ *  @return This method returns TRUE if @a the_mutex is NULL and FALSE
+ *          otherwise.
  */
- 
 RTEMS_INLINE_ROUTINE bool _POSIX_Mutex_Is_null (
   POSIX_Mutex_Control *the_mutex
 )