[rtems commit] posix: Doxygen enhancement task #4

Gedare Bloom gedare at rtems.org
Fri Dec 14 01:46:55 UTC 2012


Module:    rtems
Branch:    master
Commit:    a0e6c73850390b97a1f620173fa78802440d2168
Changeset: http://git.rtems.org/rtems/commit/?id=a0e6c73850390b97a1f620173fa78802440d2168

Author:    Mathew Kallada <matkallada at gmail.com>
Date:      Thu Dec 13 20:51:15 2012 -0500

posix: Doxygen enhancement task #4

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

---

 cpukit/posix/include/mqueue.h                   |   23 ++++++++++++++++++++++-
 cpukit/posix/include/rtems/posix/cond.h         |   12 +++++++++++-
 cpukit/posix/include/rtems/posix/key.h          |   10 ++++++++--
 cpukit/posix/include/rtems/posix/ptimer.h       |   10 +++++++++-
 cpukit/posix/include/rtems/posix/threadsup.h    |   13 ++++++++++++-
 cpukit/posix/include/rtems/posix/time.h         |    7 +++++++
 cpukit/posix/include/rtems/posix/timer.h        |   10 +++++++++-
 cpukit/posix/src/barrierattrgetpshared.c        |    7 +++++++
 cpukit/posix/src/cleanuppush.c                  |    7 +++++++
 cpukit/posix/src/clocksettime.c                 |    7 +++++++
 cpukit/posix/src/cond.c                         |    7 +++++++
 cpukit/posix/src/condsignalsupp.c               |    7 +++++++
 cpukit/posix/src/condtimedwait.c                |    7 +++++++
 cpukit/posix/src/key.c                          |    7 +++++++
 cpukit/posix/src/mprotect.c                     |    7 +++++++
 cpukit/posix/src/mqueueunlink.c                 |   19 +++++++------------
 cpukit/posix/src/mutexattrgetprioceiling.c      |    7 +++++++
 cpukit/posix/src/posixtimespecabsolutetimeout.c |    7 +++++--
 cpukit/posix/src/prwlocktrywrlock.c             |    9 +++++++--
 cpukit/posix/src/pspintrylock.c                 |    9 +++++++--
 cpukit/posix/src/pthreadexit.c                  |   11 +++++++----
 cpukit/posix/src/setcancelstate.c               |    7 +++++++
 cpukit/posix/src/sigemptyset.c                  |    9 +++++++--
 cpukit/posix/src/sigpending.c                   |    9 +++++++--
 cpukit/posix/src/sysconf.c                      |    7 +++++++
 cpukit/posix/src/timercreate.c                  |    7 +++++++
 cpukit/posix/src/timertsr.c                     |    7 +++++++
 27 files changed, 216 insertions(+), 33 deletions(-)

diff --git a/cpukit/posix/include/mqueue.h b/cpukit/posix/include/mqueue.h
index 1472983..56a97a0 100644
--- a/cpukit/posix/include/mqueue.h
+++ b/cpukit/posix/include/mqueue.h
@@ -26,6 +26,13 @@
 #include <rtems/system.h>
 #include <rtems/score/object.h>
 
+/**
+ *  @defgroup POSIX_MQUEUE Message Queues
+ *
+ *  @ingroup POSIX
+ */
+/**@{*/
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -72,7 +79,21 @@ int mq_close(
 );
 
 /**
+ *  @brief Remove a Message Queue
+ *
  *  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.]
+ *
+ *         This code ignores the O_RDONLY/O_WRONLY/O_RDWR flag at open
+ *         time.
  */
 int mq_unlink(
   const char *name
@@ -167,6 +188,6 @@ int mq_getattr(
 #endif
 
 #endif /* _POSIX_MESSAGE_PASSING */
-
+/**@}*/
 #endif
 /* end of include file */
diff --git a/cpukit/posix/include/rtems/posix/cond.h b/cpukit/posix/include/rtems/posix/cond.h
index 4b22dff..b089abe 100644
--- a/cpukit/posix/include/rtems/posix/cond.h
+++ b/cpukit/posix/include/rtems/posix/cond.h
@@ -17,6 +17,12 @@
 #ifndef _RTEMS_POSIX_COND_H
 #define _RTEMS_POSIX_COND_H
 
+/**
+ *  @defgroup POSIX_COND_VARS Condition Variables
+ *
+ *  @ingroup POSIX
+ */
+/**@{*/
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -56,6 +62,8 @@ POSIX_EXTERN Objects_Information  _POSIX_Condition_variables_Information;
 extern const pthread_condattr_t _POSIX_Condition_variables_Default_attributes;
 
 /*
+ * @brief Initialization Necessary for this Manager
+ *
  *  _POSIX_Condition_variables_Manager_initialization
  *
  *  DESCRIPTION:
@@ -125,6 +133,8 @@ RTEMS_INLINE_ROUTINE bool _POSIX_Condition_variables_Is_null (
 );
 
 /*
+ * @brief Implements wake up version of the "signal" operation
+ *
  *  _POSIX_Condition_variables_Signal_support
  *
  *  DESCRIPTION:
@@ -174,6 +184,6 @@ POSIX_Condition_variables_Control *_POSIX_Condition_variables_Get (
 #ifdef __cplusplus
 }
 #endif
-
+/**@}*/
 #endif
 /*  end of include file */
diff --git a/cpukit/posix/include/rtems/posix/key.h b/cpukit/posix/include/rtems/posix/key.h
index e056d8d..ce4f093 100644
--- a/cpukit/posix/include/rtems/posix/key.h
+++ b/cpukit/posix/include/rtems/posix/key.h
@@ -19,6 +19,12 @@
 
 #include <rtems/score/object.h>
 
+/**
+ *  @defgroup POSIX_KEY Key
+ *
+ *  @ingroup POSIX
+ */
+/**@{*/
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -45,7 +51,7 @@ 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.
  */
@@ -95,6 +101,6 @@ RTEMS_INLINE_ROUTINE void _POSIX_Keys_Free (
 #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 046a7af..a7c0837 100644
--- a/cpukit/posix/include/rtems/posix/ptimer.h
+++ b/cpukit/posix/include/rtems/posix/ptimer.h
@@ -20,6 +20,12 @@
 #ifndef _RTEMS_POSIX_PTIMER_H
 #define _RTEMS_POSIX_PTIMER_H
 
+/**
+ *  @defgroup POSIX_PRIV_TIMERS Timers
+ *
+ *  @ingroup POSIX
+ */
+/**@{*/
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -37,6 +43,8 @@ extern "C" {
 void _POSIX_Timer_Manager_initialization(void);
 
 /*
+ *  @brief Create a Per-Process Timer
+ *
  *  14.2.2 Create a Per-Process Timer, P1003.1b-1993, p. 264
  *
  *  timer_create
@@ -90,5 +98,5 @@ int timer_gettime(
 int timer_getoverrun(
   timer_t   timerid
 );
-
+/**@}*/
 #endif
diff --git a/cpukit/posix/include/rtems/posix/threadsup.h b/cpukit/posix/include/rtems/posix/threadsup.h
index 82f82b4..c5a2e3d 100644
--- a/cpukit/posix/include/rtems/posix/threadsup.h
+++ b/cpukit/posix/include/rtems/posix/threadsup.h
@@ -20,6 +20,12 @@
 #include <rtems/score/coresem.h>
 #include <rtems/score/tqdata.h>
 
+/**
+ *  @defgroup POSIX_THREAD Thread API Extension
+ *
+ *  @ingroup POSIX
+ */
+/**@{*/
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -75,12 +81,17 @@ typedef struct {
 /*!
  *  @brief POSIX Thread Exit Shared Helper
  *
+ *  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.
  *
  *  @param[in] the_thread is the thread exiting or being canceled
  *  @param[in] value_ptr is the value to be returned by the thread
+ *
+ *  NOTE: Key destructors are executed in the POSIX api delete extension.
+ *
  */
 void _POSIX_Thread_Exit(
   Thread_Control *the_thread,
@@ -90,6 +101,6 @@ void _POSIX_Thread_Exit(
 #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 104997f..d0dc4a2 100644
--- a/cpukit/posix/include/rtems/posix/time.h
+++ b/cpukit/posix/include/rtems/posix/time.h
@@ -19,6 +19,12 @@
 
 #include <rtems/score/timespec.h>
 #include <rtems/score/watchdog.h>
+/**
+ *  @defgroup POSIX_TIMETYPES Time Types
+ *
+ *  @ingroup POSIX
+ */
+/**@{*/
 
 /**
  *  @brief Absolute Timeout Conversion Results
@@ -59,3 +65,4 @@ POSIX_Absolute_timeout_conversion_results_t _POSIX_Absolute_timeout_to_ticks(
 );
 
 #endif
+/**@}*/
diff --git a/cpukit/posix/include/rtems/posix/timer.h b/cpukit/posix/include/rtems/posix/timer.h
index d193a88..1298178 100644
--- a/cpukit/posix/include/rtems/posix/timer.h
+++ b/cpukit/posix/include/rtems/posix/timer.h
@@ -21,6 +21,12 @@
 #include <rtems/score/object.h>
 #include <rtems/score/watchdog.h> /* Watchdog_Control */
 
+/**
+ *  @defgroup POSIX_INTERNAL_TIMERS Timers
+ *
+ *  @ingroup POSIX
+ */
+/**@{*/
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -75,6 +81,8 @@ typedef struct {
 void _POSIX_Timer_Manager_initialization(void);
 
 /*
+ *  @brief Operation that is run when a timer expires
+ *
  *  Timer TSR
  */
 void _POSIX_Timer_TSR(Objects_Id timer, void *data);
@@ -103,6 +111,6 @@ POSIX_EXTERN Objects_Information  _POSIX_Timer_Information;
 #ifdef __cplusplus
 }
 #endif
-
+/**@}*/
 #endif
 /* end of include file */
diff --git a/cpukit/posix/src/barrierattrgetpshared.c b/cpukit/posix/src/barrierattrgetpshared.c
index 837c050..1141fa5 100644
--- a/cpukit/posix/src/barrierattrgetpshared.c
+++ b/cpukit/posix/src/barrierattrgetpshared.c
@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief Barrier Attributes Get Process Shared
+ * @ingroup POSIX
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/posix/src/cleanuppush.c b/cpukit/posix/src/cleanuppush.c
index 23f022e..87df540 100644
--- a/cpukit/posix/src/cleanuppush.c
+++ b/cpukit/posix/src/cleanuppush.c
@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief Establishing Cancellation Handlers
+ * @ingroup POSIX
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/posix/src/clocksettime.c b/cpukit/posix/src/clocksettime.c
index de2c20d..7e7edb4 100644
--- a/cpukit/posix/src/clocksettime.c
+++ b/cpukit/posix/src/clocksettime.c
@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief Set Time of Clock
+ * @ingroup POSIX
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/posix/src/cond.c b/cpukit/posix/src/cond.c
index b66509f..d2f3b81 100644
--- a/cpukit/posix/src/cond.c
+++ b/cpukit/posix/src/cond.c
@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief Initialization Necessary for this Manager
+ * @ingroup POSIX_COND_VARS Condition Variables
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/posix/src/condsignalsupp.c b/cpukit/posix/src/condsignalsupp.c
index 5ab6e9d..36bb60e 100644
--- a/cpukit/posix/src/condsignalsupp.c
+++ b/cpukit/posix/src/condsignalsupp.c
@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief Implements wake up version of the "signal" operation
+ * @ingroup POSIX_COND_VARS Condition Variables
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/posix/src/condtimedwait.c b/cpukit/posix/src/condtimedwait.c
index 2789e21..031376c 100644
--- a/cpukit/posix/src/condtimedwait.c
+++ b/cpukit/posix/src/condtimedwait.c
@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief Waiting on a Condition
+ * @ingroup POSIX
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/posix/src/key.c b/cpukit/posix/src/key.c
index ee8b496..6eace26 100644
--- a/cpukit/posix/src/key.c
+++ b/cpukit/posix/src/key.c
@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief POSIX Keys Manager Initialization
+ * @ingroup POSIX_KEY Key
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/posix/src/mprotect.c b/cpukit/posix/src/mprotect.c
index 9d3c0eb..32de472 100644
--- a/cpukit/posix/src/mprotect.c
+++ b/cpukit/posix/src/mprotect.c
@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief Change Memory Protection
+ * @ingroup POSIX
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/posix/src/mqueueunlink.c b/cpukit/posix/src/mqueueunlink.c
index 8e48ffe..0f68ae7 100644
--- a/cpukit/posix/src/mqueueunlink.c
+++ b/cpukit/posix/src/mqueueunlink.c
@@ -1,16 +1,11 @@
-/*
- *  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.
+/**
+ * @file
  *
+ * @brief Remove a Message Queue
+ * @ingroup POSIX_MQUEUE Message Queues
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/posix/src/mutexattrgetprioceiling.c b/cpukit/posix/src/mutexattrgetprioceiling.c
index a571ad5..949fd3b 100644
--- a/cpukit/posix/src/mutexattrgetprioceiling.c
+++ b/cpukit/posix/src/mutexattrgetprioceiling.c
@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief Mutex Initialization Scheduling Attributes
+ * @ingroup POSIX
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/posix/src/posixtimespecabsolutetimeout.c b/cpukit/posix/src/posixtimespecabsolutetimeout.c
index 24362c5..e94805e 100644
--- a/cpukit/posix/src/posixtimespecabsolutetimeout.c
+++ b/cpukit/posix/src/posixtimespecabsolutetimeout.c
@@ -1,5 +1,8 @@
-/*
- *  Convert abstime timeout to ticks
+/**
+ * @file
+ *
+ * @brief Convert Absolute Timeout to Ticks
+ * @ingroup POSIX_TIMETYPES Time Types
  */
 
 /*
diff --git a/cpukit/posix/src/prwlocktrywrlock.c b/cpukit/posix/src/prwlocktrywrlock.c
index 06a3cbb..f8857a8 100644
--- a/cpukit/posix/src/prwlocktrywrlock.c
+++ b/cpukit/posix/src/prwlocktrywrlock.c
@@ -1,6 +1,11 @@
-/*
- *  POSIX RWLock Manager -- Attempt to Obtain a Write Lock on a RWLock Instance
+/**
+ * @file
  *
+ * @brief Attempt to Obtain a Write Lock on a RWLock Instance
+ * @ingroup POSIX
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/posix/src/pspintrylock.c b/cpukit/posix/src/pspintrylock.c
index e3f2659..de89b4e 100644
--- a/cpukit/posix/src/pspintrylock.c
+++ b/cpukit/posix/src/pspintrylock.c
@@ -1,6 +1,11 @@
-/*
- *  POSIX Spinlock Manager -- Wait at a Spinlock
+/**
+ * @file
  *
+ * @brief Wait at a Spinlock
+ * @ingroup POSIX
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/posix/src/pthreadexit.c b/cpukit/posix/src/pthreadexit.c
index e89ed85..2e995c4 100644
--- a/cpukit/posix/src/pthreadexit.c
+++ b/cpukit/posix/src/pthreadexit.c
@@ -1,8 +1,11 @@
-/*
- *  16.1.5.1 Thread Termination, p1003.1c/Draft 10, p. 150
- *
- *  NOTE: Key destructors are executed in the POSIX api delete extension.
+/**
+ * @file
  *
+ * @brief POSIX Thread Exit Shared Helper
+ * @ingroup POSIX_THREAD Thread API Extension
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2011.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/posix/src/setcancelstate.c b/cpukit/posix/src/setcancelstate.c
index a5356aa..31bef65 100644
--- a/cpukit/posix/src/setcancelstate.c
+++ b/cpukit/posix/src/setcancelstate.c
@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief Setting Cancelability State
+ * @ingroup POSIX
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2009.
  *  On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/posix/src/sigemptyset.c b/cpukit/posix/src/sigemptyset.c
index 245639e..5cfc310 100644
--- a/cpukit/posix/src/sigemptyset.c
+++ b/cpukit/posix/src/sigemptyset.c
@@ -1,6 +1,11 @@
-/*
- *  3.3.3 Manipulate Signal Sets, P1003.1b-1993, p. 69
+/**
+ * @file
  *
+ * @brief Manipulate Signal Sets
+ * @ingroup POSIX
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/posix/src/sigpending.c b/cpukit/posix/src/sigpending.c
index 9145c98..c62d878 100644
--- a/cpukit/posix/src/sigpending.c
+++ b/cpukit/posix/src/sigpending.c
@@ -1,6 +1,11 @@
-/*
- *  3.3.6 Examine Pending Signals, P1003.1b-1993, p. 75
+/**
+ * @file
  *
+ * @brief Examine Pending Signals
+ * @ingroup POSIX
+ */
+
+/*
  *  COPYRIGHT (c) 1989-1999.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/posix/src/sysconf.c b/cpukit/posix/src/sysconf.c
index e6c73de..fb0939f 100644
--- a/cpukit/posix/src/sysconf.c
+++ b/cpukit/posix/src/sysconf.c
@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief Get Configurable System Variables
+ * @ingroup POSIX
+ */
+
 /*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/posix/src/timercreate.c b/cpukit/posix/src/timercreate.c
index 6dfa75b..bd52f87 100644
--- a/cpukit/posix/src/timercreate.c
+++ b/cpukit/posix/src/timercreate.c
@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief Create a Per-Process Timer
+ * @ingroup POSIX_PRIV_TIMERS Timers
+ */
+
 /*
  *  14.2.2 Create a Per-Process Timer, P1003.1b-1993, p. 264
  *
diff --git a/cpukit/posix/src/timertsr.c b/cpukit/posix/src/timertsr.c
index 0ef40ff..ad17ae9 100644
--- a/cpukit/posix/src/timertsr.c
+++ b/cpukit/posix/src/timertsr.c
@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief Operation that is run when a timer expires
+ * @ingroup POSIX_INTERNAL_TIMERS Timers
+ */
+
 /*
  * _POSIX_Timer_TSR
  *




More information about the vc mailing list