[rtems commit] Score misc: Clean up Doxygen #8 (GCI 2012)
Joel Sherrill
joel at rtems.org
Fri Nov 30 01:59:00 UTC 2012
Module: rtems
Branch: master
Commit: 8396c18ee6eb60403730e5aa2480474c6109f823
Changeset: http://git.rtems.org/rtems/commit/?id=8396c18ee6eb60403730e5aa2480474c6109f823
Author: Mathew Kallada <matkallada at gmail.com>
Date: Thu Nov 29 20:01:26 2012 -0600
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 53976e6..ebb0f24 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 1784586..29c98a8 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 dbda8b2..117f86a 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 c15114c..6716383 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 8ba4c9b..eb92772 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 302ca34..5774118 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 991a229..82a491f 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 <rtems/score/chain.h>
#include <rtems/score/isr.h>
-/*
- * _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 33cd942..86ac501 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 b94b699..a6a5c25 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 2672595..16e16cd 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 fae262a..1b88e06 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 <rtems/score/isr.h>
#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 625eb49..2bc86cf 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 <inttypes.h>
#include <string.h>
-
-/*
- * 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 0e0e8ce..2ee37e7 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 d04efa5..6b1db63 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 913aa57..83712ce 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 4023100..31ed640 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 d0f6d47..ea3c2c4 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 d34bd89..e41fa96 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 5c8233a..9d6d979 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 84b5f19..1d5d48c 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 cfeb050..8209d58 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 <rtems/score/threadq.h>
#include <rtems/score/tqdata.h>
-/*
- * _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 53b20da..a8fb602 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 b35a69c..f1b9758 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 5924db7..e77c22a 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
More information about the vc
mailing list