From 8396c18ee6eb60403730e5aa2480474c6109f823 Mon Sep 17 00:00:00 2001 From: Mathew Kallada Date: Thu, 29 Nov 2012 20:01:26 -0600 Subject: Score misc: Clean up Doxygen #8 (GCI 2012) This patch is a task from GCI 2012 which improves the Doxygen comments in the RTEMS source. http://www.google-melange.com/gci/task/view/google/gci2012/7970221 --- cpukit/score/include/rtems/score/chain.h | 8 +++++-- cpukit/score/include/rtems/score/object.h | 20 +++++++++++------ cpukit/score/include/rtems/score/scheduler.h | 2 ++ cpukit/score/include/rtems/score/schedulersimple.h | 6 +++-- cpukit/score/src/apimutexallocate.c | 7 ++++++ cpukit/score/src/chainappend.c | 7 ++++++ cpukit/score/src/chainget.c | 24 ++++++-------------- cpukit/score/src/coremutexsurrender.c | 14 ++++++------ cpukit/score/src/objectextendinformation.c | 10 ++++++--- cpukit/score/src/objectgetnext.c | 10 ++++++--- cpukit/score/src/objectnametoidstring.c | 26 ++++++---------------- cpukit/score/src/objectsetname.c | 12 +++++----- cpukit/score/src/scheduler.c | 9 ++++++-- cpukit/score/src/scheduleredf.c | 7 ++++++ cpukit/score/src/scheduleredfreleasejob.c | 7 ++++++ cpukit/score/src/scheduleredfunblock.c | 7 ++++++ .../score/src/schedulersimplereadyqueueenqueue.c | 9 ++++++-- cpukit/score/src/schedulersimpleschedule.c | 9 ++++++-- cpukit/score/src/schedulersimplesmpblock.c | 9 ++++++-- cpukit/score/src/schedulersimpleyield.c | 9 ++++++-- cpukit/score/src/threadqflush.c | 23 ++++++------------- cpukit/score/src/ts64lessthan.c | 5 ++++- cpukit/score/src/ts64toticks.c | 5 ++++- cpukit/score/src/watchdogreport.c | 6 +++-- 24 files changed, 156 insertions(+), 95 deletions(-) diff --git a/cpukit/score/include/rtems/score/chain.h b/cpukit/score/include/rtems/score/chain.h index 53976e6d78..ebb0f24e8c 100644 --- a/cpukit/score/include/rtems/score/chain.h +++ b/cpukit/score/include/rtems/score/chain.h @@ -162,8 +162,9 @@ Chain_Node *_Chain_Get( * * This routine inserts @a the_node on a chain immediately following * @a after_node. - * - * @param[in] after_node is the pointer to the node in chain to be inserted after + * + * @param[in] after_node is the pointer to the node in chain to be + * inserted after * @param[in] node is the pointer to the node to be inserted * * @note It disables interrupts to ensure the atomicity @@ -244,6 +245,9 @@ bool _Chain_Prepend_with_empty_check( * * @retval true The chain is empty now. * @retval false The chain contains at least one node now. + * + * - INTERRUPT LATENCY: + * + single case */ bool _Chain_Get_with_empty_check( Chain_Control *the_chain, diff --git a/cpukit/score/include/rtems/score/object.h b/cpukit/score/include/rtems/score/object.h index 178458681e..29c98a8183 100644 --- a/cpukit/score/include/rtems/score/object.h +++ b/cpukit/score/include/rtems/score/object.h @@ -448,12 +448,12 @@ void _Objects_Extend_information( /** * @brief Shrink an object class information record - * + * * This function shrink an object class information record. * The object's name and object space are released. The local_table * etc block does not shrink. The InActive list needs to be scanned * to find the objects are remove them. - * + * * @param[in] information points to an object class information block. */ void _Objects_Shrink_information( @@ -462,7 +462,7 @@ void _Objects_Shrink_information( /** * @brief Initialize object Information - * + * * This function initializes an object class information record. * SUPPORTS_GLOBAL is true if the object class supports global * objects, and false otherwise. Maximum indicates the number @@ -516,6 +516,8 @@ unsigned int _Objects_API_maximum_class( * This function allocates a object control block from * the inactive chain of free object control blocks. * + * @brief Allocate Object + * * @param[in] information points to an object class information block. */ Objects_Control *_Objects_Allocate( @@ -604,6 +606,8 @@ Objects_Name_or_id_lookup_errors _Objects_Name_to_id_u32( #if defined(RTEMS_SCORE_OBJECT_ENABLE_STRING_NAMES) /** + * @brief Object ID to Name + * * This method converts an object name to an Id. It performs a look up * using the object information block for this object class. * @@ -675,7 +679,7 @@ Objects_Control *_Objects_Get ( /** * @brief Object Get Isr Disable - * + * * This function maps object ids to object control blocks. * If id corresponds to a local object, then it returns * the_object control pointer which maps to id and location @@ -709,7 +713,7 @@ Objects_Control *_Objects_Get_isr_disable( /** * @brief Get No protection Object - * + * * This function maps object ids to object control blocks. * If id corresponds to a local object, then it returns * the_object control pointer which maps to id and location @@ -759,7 +763,7 @@ Objects_Control *_Objects_Get_next( /** * @brief Get Object Information - * + * * This function return the information structure given * an the API and Class. This can be done independent of * the existence of any objects created by the API. @@ -790,7 +794,7 @@ Objects_Information *_Objects_Get_information_id( /** * @brief _Objects_Get_name_as_string - * + * * This method objects the name of an object and returns its name * in the form of a C string. It attempts to be careful about * overflowing the user's string and about returning unprintable characters. @@ -809,6 +813,8 @@ char *_Objects_Get_name_as_string( ); /** + * @brief Set Objects Name + * * This method sets the object name to either a copy of a string * or up to the first four characters of the string based upon * whether this object class uses strings for names. diff --git a/cpukit/score/include/rtems/score/scheduler.h b/cpukit/score/include/rtems/score/scheduler.h index dbda8b2d67..117f86a37a 100644 --- a/cpukit/score/include/rtems/score/scheduler.h +++ b/cpukit/score/include/rtems/score/scheduler.h @@ -129,6 +129,8 @@ extern Scheduler_Control _Scheduler; (_Scheduler_Priority_compare(_p1,_p2) > 0) /** + * @brief Scheduler is priority higher than + * * This routine initializes the scheduler to the policy chosen by the user * through confdefs, or to the priority scheduler with ready chains by * default. diff --git a/cpukit/score/include/rtems/score/schedulersimple.h b/cpukit/score/include/rtems/score/schedulersimple.h index c15114c6c8..6716383205 100644 --- a/cpukit/score/include/rtems/score/schedulersimple.h +++ b/cpukit/score/include/rtems/score/schedulersimple.h @@ -64,6 +64,8 @@ void _Scheduler_simple_Initialize( void ); void _Scheduler_simple_Schedule( void ); /** + * @brief Simple Schedule + * * This routine is invoked when a thread wishes to voluntarily * transfer control of the processor to another thread in the queue. * It will remove the running THREAD from the scheduler.informaiton @@ -126,7 +128,7 @@ void _Scheduler_simple_Enqueue( /** * @brief Scheduler simple Enqueue first - * + * * This routine puts @a the_thread to the head of the ready queue. * The thread will be the first thread at its priority level. * @@ -166,7 +168,7 @@ void _Scheduler_simple_Update( ); /** - * @brief Stub for schedule free + * @brief Stub for schedule free * * This routine does nothing, and is used as a stub for Schedule free * The overhead of a function call will still be imposed. diff --git a/cpukit/score/src/apimutexallocate.c b/cpukit/score/src/apimutexallocate.c index 8ba4c9b87e..eb92772332 100644 --- a/cpukit/score/src/apimutexallocate.c +++ b/cpukit/score/src/apimutexallocate.c @@ -1,3 +1,10 @@ +/** + * @file + * + * @brief Allocates an API Mutex from the Inactive Set + * @ingroup ScoreAPIMutex + */ + /* * COPYRIGHT (c) 1989-2007. * On-Line Applications Research Corporation (OAR). diff --git a/cpukit/score/src/chainappend.c b/cpukit/score/src/chainappend.c index 302ca34f32..5774118aeb 100644 --- a/cpukit/score/src/chainappend.c +++ b/cpukit/score/src/chainappend.c @@ -1,3 +1,10 @@ +/** + * @file + * + * @brief Append a Node on the End of a Chain + * @ingroup ScoreChain +*/ + /* * COPYRIGHT (c) 1989-2007. * On-Line Applications Research Corporation (OAR). diff --git a/cpukit/score/src/chainget.c b/cpukit/score/src/chainget.c index 991a22910b..82a491fac1 100644 --- a/cpukit/score/src/chainget.c +++ b/cpukit/score/src/chainget.c @@ -1,3 +1,10 @@ +/** + * @file + * + * @brief Get the First Node + * @ingroup ScoreChain + */ + /* * COPYRIGHT (c) 1989-2007. * On-Line Applications Research Corporation (OAR). @@ -16,23 +23,6 @@ #include #include -/* - * _Chain_Get - * - * This kernel routine returns a pointer to a node taken from the - * given chain. - * - * Input parameters: - * the_chain - pointer to chain header - * - * Output parameters: - * return_node - pointer to node in chain allocated - * CHAIN_END - if no nodes available - * - * INTERRUPT LATENCY: - * only case - */ - Chain_Node *_Chain_Get( Chain_Control *the_chain ) diff --git a/cpukit/score/src/coremutexsurrender.c b/cpukit/score/src/coremutexsurrender.c index 33cd942bd6..86ac501ca3 100644 --- a/cpukit/score/src/coremutexsurrender.c +++ b/cpukit/score/src/coremutexsurrender.c @@ -1,11 +1,11 @@ -/* - * Mutex Handler - * - * DESCRIPTION: - * - * This package is the implementation of the Mutex Handler. - * This handler provides synchronization and mutual exclusion capabilities. +/** + * @file * + * @brief Surrender the Mutex + * @ingroup ScoreMutex + */ + +/* * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). * diff --git a/cpukit/score/src/objectextendinformation.c b/cpukit/score/src/objectextendinformation.c index b94b699835..a6a5c253a1 100644 --- a/cpukit/score/src/objectextendinformation.c +++ b/cpukit/score/src/objectextendinformation.c @@ -1,7 +1,11 @@ -/* - * Object Handler - * +/** + * @file * + * @brief Extend Set of Objects + * @ingroup ScoreObject + */ + +/* * COPYRIGHT (c) 1989-1999. * On-Line Applications Research Corporation (OAR). * diff --git a/cpukit/score/src/objectgetnext.c b/cpukit/score/src/objectgetnext.c index 26725957d6..16e16cd8d8 100644 --- a/cpukit/score/src/objectgetnext.c +++ b/cpukit/score/src/objectgetnext.c @@ -1,7 +1,11 @@ -/* - * Object Handler - * +/** + * @file * + * @brief Get Pointer to Next Object that is Active + * @ingroup ScoreObject + */ + +/* * COPYRIGHT (c) 1989-1999. * On-Line Applications Research Corporation (OAR). * diff --git a/cpukit/score/src/objectnametoidstring.c b/cpukit/score/src/objectnametoidstring.c index fae262a7db..1b88e06fb4 100644 --- a/cpukit/score/src/objectnametoidstring.c +++ b/cpukit/score/src/objectnametoidstring.c @@ -1,6 +1,11 @@ -/* - * Object Handler - Object ID to Name (String) +/** + * @file * + * @brief Object ID to Name + * @ingroup ScoreObject + */ + +/* * COPYRIGHT (c) 1989-2010. * On-Line Applications Research Corporation (OAR). * @@ -28,23 +33,6 @@ #include #if defined(RTEMS_SCORE_OBJECT_ENABLE_STRING_NAMES) -/* - * _Objects_Name_to_id_string - * - * These kernel routines search the object table(s) for the given - * object name and returns the associated object id. - * - * Input parameters: - * information - object information - * name - user defined object name - * id - address of return ID - * - * Output parameters: - * id - object id - * OBJECTS_NAME_OR_ID_LOOKUP_SUCCESSFUL - if successful - * error code - if unsuccessful - */ - Objects_Name_or_id_lookup_errors _Objects_Name_to_id_string( Objects_Information *information, const char *name, diff --git a/cpukit/score/src/objectsetname.c b/cpukit/score/src/objectsetname.c index 625eb496f3..2bc86cf553 100644 --- a/cpukit/score/src/objectsetname.c +++ b/cpukit/score/src/objectsetname.c @@ -1,3 +1,10 @@ +/** + * @file + * + * @brief Set Objects Name + * @ingroup ScoreObject + */ + /* * COPYRIGHT (c) 1989-2009. * On-Line Applications Research Corporation (OAR). @@ -20,11 +27,6 @@ #include #include - -/* - * This method sets the name of an object based upon a C string. - */ - bool _Objects_Set_name( Objects_Information *information, Objects_Control *the_object, diff --git a/cpukit/score/src/scheduler.c b/cpukit/score/src/scheduler.c index 0e0e8cec05..2ee37e7634 100644 --- a/cpukit/score/src/scheduler.c +++ b/cpukit/score/src/scheduler.c @@ -1,6 +1,11 @@ -/* - * Scheduler Handler / Initialization +/** + * @file * + * @brief Scheduler Initialize + * @ingroup ScoreScheduler + */ + +/* * Copyright (C) 2010 Gedare Bloom. * Copyright (C) 2011 On-Line Applications Research Corporation (OAR). * diff --git a/cpukit/score/src/scheduleredf.c b/cpukit/score/src/scheduleredf.c index d04efa56d2..6b1db632b2 100644 --- a/cpukit/score/src/scheduleredf.c +++ b/cpukit/score/src/scheduleredf.c @@ -1,3 +1,10 @@ +/** + * @file + * + * @brief Scheduler EDF Initialize and Support + * @ingroup ScoreScheduler + */ + /* * Copyright (C) 2011 Petr Benes. * Copyright (C) 2011 On-Line Applications Research Corporation (OAR). diff --git a/cpukit/score/src/scheduleredfreleasejob.c b/cpukit/score/src/scheduleredfreleasejob.c index 913aa57704..83712ce162 100644 --- a/cpukit/score/src/scheduleredfreleasejob.c +++ b/cpukit/score/src/scheduleredfreleasejob.c @@ -1,3 +1,10 @@ +/** + * @file + * + * @brief Scheduler EDF Release Job + * @ingroup ScoreScheduler + */ + /* * Copyright (C) 2011 Petr Benes. * Copyright (C) 2011 On-Line Applications Research Corporation (OAR). diff --git a/cpukit/score/src/scheduleredfunblock.c b/cpukit/score/src/scheduleredfunblock.c index 4023100aab..31ed6401af 100644 --- a/cpukit/score/src/scheduleredfunblock.c +++ b/cpukit/score/src/scheduleredfunblock.c @@ -1,3 +1,10 @@ +/** + * @file + * + * @brief Scheduler EDF Unblock + * @ingroup ScoreScheduler + */ + /* * Copyright (C) 2011 Petr Benes. * Copyright (C) 2011 On-Line Applications Research Corporation (OAR). diff --git a/cpukit/score/src/schedulersimplereadyqueueenqueue.c b/cpukit/score/src/schedulersimplereadyqueueenqueue.c index d0f6d473f3..ea3c2c45ec 100644 --- a/cpukit/score/src/schedulersimplereadyqueueenqueue.c +++ b/cpukit/score/src/schedulersimplereadyqueueenqueue.c @@ -1,6 +1,11 @@ -/* - * Schedule Simple Handler / Ready Queue Enqueue +/** + * @file * + * @brief Scheduler Simple Priority Enqueue Ready Thread + * @ingroup ScoreScheduler + */ + +/* * COPYRIGHT (c) 2011. * On-Line Applications Research Corporation (OAR). * diff --git a/cpukit/score/src/schedulersimpleschedule.c b/cpukit/score/src/schedulersimpleschedule.c index d34bd89a22..e41fa96483 100644 --- a/cpukit/score/src/schedulersimpleschedule.c +++ b/cpukit/score/src/schedulersimpleschedule.c @@ -1,6 +1,11 @@ -/* - * Scheduler Simple Handler / Schedule +/** + * @file * + * @brief Simple Schedule Determine Heir + * @ingroup ScoreScheduler + */ + +/* * COPYRIGHT (c) 2011. * On-Line Applications Research Corporation (OAR). * diff --git a/cpukit/score/src/schedulersimplesmpblock.c b/cpukit/score/src/schedulersimplesmpblock.c index 5c8233a840..9d6d979684 100644 --- a/cpukit/score/src/schedulersimplesmpblock.c +++ b/cpukit/score/src/schedulersimplesmpblock.c @@ -1,6 +1,11 @@ -/* - * Scheduler Simple SMP Handler / Block +/** + * @file * + * @brief Scheduler Simple Block + * @ingroup ScoreScheduler + */ + +/* * COPYRIGHT (c) 2011. * On-Line Applications Research Corporation (OAR). * diff --git a/cpukit/score/src/schedulersimpleyield.c b/cpukit/score/src/schedulersimpleyield.c index 84b5f19595..1d5d48c7e5 100644 --- a/cpukit/score/src/schedulersimpleyield.c +++ b/cpukit/score/src/schedulersimpleyield.c @@ -1,6 +1,11 @@ -/* - * Scheduler Simple Handler / Yield +/** + * @file * + * @brief Simple Schedule Yield CPU + * @ingroup ScoreScheduler + */ + +/* * COPYRIGHT (c) 2011. * On-Line Applications Research Corporation (OAR). * diff --git a/cpukit/score/src/threadqflush.c b/cpukit/score/src/threadqflush.c index cfeb0501eb..8209d5802c 100644 --- a/cpukit/score/src/threadqflush.c +++ b/cpukit/score/src/threadqflush.c @@ -1,7 +1,11 @@ -/* - * Thread Queue Handler - * +/** + * @file * + * @brief Thread Queue Flush + * @ingroup ScoreThreadQ + */ + +/* * COPYRIGHT (c) 1989-2008. * On-Line Applications Research Corporation (OAR). * @@ -23,19 +27,6 @@ #include #include -/* - * _Thread_queue_Flush - * - * This kernel routine flushes the given thread queue. - * - * Input parameters: - * the_thread_queue - pointer to threadq to be flushed - * remote_extract_callout - pointer to routine which extracts a remote thread - * status - status to return to the thread - * - * Output parameters: NONE - */ - void _Thread_queue_Flush( Thread_queue_Control *the_thread_queue, #if defined(RTEMS_MULTIPROCESSING) diff --git a/cpukit/score/src/ts64lessthan.c b/cpukit/score/src/ts64lessthan.c index 53b20daae7..a8fb602e7b 100644 --- a/cpukit/score/src/ts64lessthan.c +++ b/cpukit/score/src/ts64lessthan.c @@ -1,5 +1,8 @@ /** - * @file score/src/ts64lessthan.c + * @file + * + * @brief Timestamp Less Than Operator + * @ingroup SuperCore Timestamp64 */ /* diff --git a/cpukit/score/src/ts64toticks.c b/cpukit/score/src/ts64toticks.c index b35a69c60e..f1b97587d2 100644 --- a/cpukit/score/src/ts64toticks.c +++ b/cpukit/score/src/ts64toticks.c @@ -1,5 +1,8 @@ /** - * @file score/src/ts64toticks.c + * @file + * + * @brief Convert 64-bit Timestamp to Number of Ticks + * @ingroup SuperCore Timestamp64 */ /* diff --git a/cpukit/score/src/watchdogreport.c b/cpukit/score/src/watchdogreport.c index 5924db784a..e77c22aeb4 100644 --- a/cpukit/score/src/watchdogreport.c +++ b/cpukit/score/src/watchdogreport.c @@ -1,10 +1,12 @@ /** * @file watchdogreport.c * - * This should only be used for debugging. + * @brief Report Information on a Single Watchdog Instance + * @ingroup ScoreWatchdog */ -/* COPYRIGHT (c) 1989-2008. +/* + * COPYRIGHT (c) 1989-2008. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be -- cgit v1.2.3