From a0e6c73850390b97a1f620173fa78802440d2168 Mon Sep 17 00:00:00 2001 From: Mathew Kallada Date: Thu, 13 Dec 2012 20:51:15 -0500 Subject: 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(-) (limited to 'cpukit') diff --git a/cpukit/posix/include/mqueue.h b/cpukit/posix/include/mqueue.h index 1472983593..56a97a0c7a 100644 --- a/cpukit/posix/include/mqueue.h +++ b/cpukit/posix/include/mqueue.h @@ -26,6 +26,13 @@ #include #include +/** + * @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 4b22dff942..b089abe4a9 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 e056d8d89a..ce4f093b13 100644 --- a/cpukit/posix/include/rtems/posix/key.h +++ b/cpukit/posix/include/rtems/posix/key.h @@ -19,6 +19,12 @@ #include +/** + * @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 046a7af477..a7c083711a 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 82f82b40c3..c5a2e3db7e 100644 --- a/cpukit/posix/include/rtems/posix/threadsup.h +++ b/cpukit/posix/include/rtems/posix/threadsup.h @@ -20,6 +20,12 @@ #include #include +/** + * @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 104997fcf8..d0dc4a27fe 100644 --- a/cpukit/posix/include/rtems/posix/time.h +++ b/cpukit/posix/include/rtems/posix/time.h @@ -19,6 +19,12 @@ #include #include +/** + * @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 d193a88b87..1298178e95 100644 --- a/cpukit/posix/include/rtems/posix/timer.h +++ b/cpukit/posix/include/rtems/posix/timer.h @@ -21,6 +21,12 @@ #include #include /* 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 837c050ef5..1141fa5a5c 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 23f022e1d1..87df540555 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 de2c20de50..7e7edb4f56 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 b66509f8da..d2f3b81618 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 5ab6e9de95..36bb60ebb2 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 2789e210c1..031376cfea 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 ee8b496b2f..6eace26eed 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 9d3c0eb09a..32de472a21 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 8e48ffe669..0f68ae727a 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 a571ad5ba2..949fd3b32c 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 24362c5aa3..e94805e692 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 06a3cbb2e5..f8857a831b 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 e3f2659735..de89b4e579 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 e89ed855c3..2e995c49bc 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 a5356aa945..31bef65eff 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 245639e896..5cfc310ba1 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 9145c988e4..c62d878b6b 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 e6c73de2ec..fb0939fbe2 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 6dfa75b9c8..bd52f87fe9 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 0ef40ffdfe..ad17ae91c2 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 * -- cgit v1.2.3