[rtems commit] score misc: Clean up Doxygen #3 (GCI 2012)
Joel Sherrill
joel at rtems.org
Wed Nov 28 19:53:43 UTC 2012
Module: rtems
Branch: master
Commit: 355ee7dbd52a1ea5fd7d8b32d31aeccd58ccb8c4
Changeset: http://git.rtems.org/rtems/commit/?id=355ee7dbd52a1ea5fd7d8b32d31aeccd58ccb8c4
Author: Alex Ivanov <alexivanov97 at gmail.com>
Date: Wed Nov 28 13:57:31 2012 -0600
score misc: Clean up Doxygen #3 (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/7982215
---
cpukit/score/include/rtems/score/coremsg.h | 9 +++++-
cpukit/score/include/rtems/score/coresem.h | 8 +++++
cpukit/score/include/rtems/score/object.h | 2 +
.../score/include/rtems/score/schedulerpriority.h | 2 +
cpukit/score/include/rtems/score/schedulersimple.h | 2 +
cpukit/score/include/rtems/score/thread.h | 2 +
cpukit/score/include/rtems/score/threadq.h | 10 ++++++
cpukit/score/src/coremsg.c | 33 ++++---------------
cpukit/score/src/coresem.c | 29 ++++-------------
cpukit/score/src/coretodget.c | 9 ++++-
cpukit/score/src/coretodtickspersec.c | 7 ++++
cpukit/score/src/objectgetnoprotection.c | 29 ++++-------------
cpukit/score/src/schedulercbscleanup.c | 7 ++++
cpukit/score/src/schedulercbscreateserver.c | 7 ++++
cpukit/score/src/schedulercbsgetapprovedbudget.c | 7 ++++
cpukit/score/src/schedulercbsgetremainingbudget.c | 7 ++++
.../score/src/schedulerpriorityprioritycompare.c | 7 ++++
cpukit/score/src/schedulerpriorityreleasejob.c | 7 ++++
cpukit/score/src/schedulerpriorityunblock.c | 7 ++++
cpukit/score/src/schedulersimpleenqueuefirst.c | 9 ++++-
cpukit/score/src/smplock.c | 13 ++++---
cpukit/score/src/threadqenqueuefifo.c | 25 ++++-----------
cpukit/score/src/threadqrequeue.c | 25 ++++-----------
cpukit/score/src/threadsetpriority.c | 9 ++++-
cpukit/score/src/ts64dividebyinteger.c | 7 +++-
cpukit/score/src/watchdogadjust.c | 24 ++++----------
26 files changed, 165 insertions(+), 138 deletions(-)
diff --git a/cpukit/score/include/rtems/score/coremsg.h b/cpukit/score/include/rtems/score/coremsg.h
index cb8ce98..c864685 100644
--- a/cpukit/score/include/rtems/score/coremsg.h
+++ b/cpukit/score/include/rtems/score/coremsg.h
@@ -257,8 +257,15 @@ typedef struct {
/**
* @brief Initialize a Message Queue
+ *
+ * DESCRIPTION:
+ *
+ * This package is the implementation of the CORE Message Queue Handler.
+ * This core object provides task synchronization and communication functions
+ * via messages passed to queue objects.
*
- * This routine initializes @a the_message_queue based on the parameters passed.
+ * This routine initializes @a the_message_queue
+ * based on the parameters passed.
*
* @param[in] the_message_queue points to the message queue to initialize
* @param[in] the_message_queue_attributes points to the attributes that
diff --git a/cpukit/score/include/rtems/score/coresem.h b/cpukit/score/include/rtems/score/coresem.h
index fc4d0ba..c8d7deb 100644
--- a/cpukit/score/include/rtems/score/coresem.h
+++ b/cpukit/score/include/rtems/score/coresem.h
@@ -127,6 +127,14 @@ typedef struct {
} CORE_semaphore_Control;
/**
+ * @brief Core Semaphore Initialize
+ *
+ * DESCRIPTION:
+ *
+ * This package is the implementation of the CORE Semaphore Handler.
+ * This core object utilizes standard Dijkstra counting semaphores to provide
+ * synchronization and mutual exclusion capabilities.
+ *
* This routine initializes the semaphore based on the parameters passed.
*
* @param[in] the_semaphore is the semaphore to initialize
diff --git a/cpukit/score/include/rtems/score/object.h b/cpukit/score/include/rtems/score/object.h
index e8ee057..c9176e7 100644
--- a/cpukit/score/include/rtems/score/object.h
+++ b/cpukit/score/include/rtems/score/object.h
@@ -697,6 +697,8 @@ 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
diff --git a/cpukit/score/include/rtems/score/schedulerpriority.h b/cpukit/score/include/rtems/score/schedulerpriority.h
index 2123968..63e3669 100644
--- a/cpukit/score/include/rtems/score/schedulerpriority.h
+++ b/cpukit/score/include/rtems/score/schedulerpriority.h
@@ -121,6 +121,8 @@ void _Scheduler_priority_Update(
);
/**
+ * @brief Scheduler Priority Unblock
+ *
* This routine adds @a the_thread to the scheduling decision,
* that is, adds it to the ready queue and
* updates any appropriate scheduling variables, for example the heir thread.
diff --git a/cpukit/score/include/rtems/score/schedulersimple.h b/cpukit/score/include/rtems/score/schedulersimple.h
index 6237e5c..97b571d 100644
--- a/cpukit/score/include/rtems/score/schedulersimple.h
+++ b/cpukit/score/include/rtems/score/schedulersimple.h
@@ -119,6 +119,8 @@ 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.
*
diff --git a/cpukit/score/include/rtems/score/thread.h b/cpukit/score/include/rtems/score/thread.h
index fdacd41..fd49b8c 100644
--- a/cpukit/score/include/rtems/score/thread.h
+++ b/cpukit/score/include/rtems/score/thread.h
@@ -708,6 +708,8 @@ void _Thread_Change_priority (
);
/**
+ * @brief Set Thread Priority
+ *
* This routine updates the priority related fields in the_thread
* control block to indicate the current priority is now new_priority.
*/
diff --git a/cpukit/score/include/rtems/score/threadq.h b/cpukit/score/include/rtems/score/threadq.h
index db832f4..1999ea1 100644
--- a/cpukit/score/include/rtems/score/threadq.h
+++ b/cpukit/score/include/rtems/score/threadq.h
@@ -109,6 +109,9 @@ void _Thread_queue_Enqueue_with_handler(
* the_thread is removed from the_thread_queue and reinserted using
* its new priority. This method has no impact on the state of the_thread
* or of any timeouts associated with this blocking.
+ *
+ * @param[in] the_thread_queue pointer to a threadq header
+ * @param[in] the_thread pointer to a thread control block
*/
void _Thread_queue_Requeue(
Thread_queue_Control *the_thread_queue,
@@ -254,6 +257,13 @@ Thread_Control *_Thread_queue_Dequeue_fifo(
* This routine enqueues the currently executing thread on
* the_thread_queue with an optional timeout using the
* FIFO discipline.
+ *
+ * @param[in] the_thread_queue pointer to threadq
+ * @param[in] the_thread pointer to the thread to block
+ * @param[in] level_p interrupt level in case the operation blocks actually
+ *
+ * - INTERRUPT LATENCY:
+ * + single case
*/
Thread_blocking_operation_States _Thread_queue_Enqueue_fifo (
Thread_queue_Control *the_thread_queue,
diff --git a/cpukit/score/src/coremsg.c b/cpukit/score/src/coremsg.c
index c55d2d5..e02989b 100644
--- a/cpukit/score/src/coremsg.c
+++ b/cpukit/score/src/coremsg.c
@@ -1,12 +1,11 @@
-/*
- * CORE Message Queue Handler
- *
- * DESCRIPTION:
- *
- * This package is the implementation of the CORE Message Queue Handler.
- * This core object provides task synchronization and communication functions
- * via messages passed to queue objects.
+/**
+ * @file
*
+ * @brief Initialize a Message Queue
+ * @ingroup ScoreMessageQueue
+ */
+
+/*
* COPYRIGHT (c) 1989-2009.
* On-Line Applications Research Corporation (OAR).
*
@@ -49,24 +48,6 @@ static inline bool size_t_mult32_with_overflow(
return true;
}
-/*
- * _CORE_message_queue_Initialize
- *
- * This routine initializes a newly created message queue based on the
- * specified data.
- *
- * Input parameters:
- * the_message_queue - the message queue to initialize
- * the_class - the API specific object class
- * the_message_queue_attributes - the message queue's attributes
- * maximum_pending_messages - maximum message and reserved buffer count
- * maximum_message_size - maximum size of each message
- *
- * Output parameters:
- * true - if the message queue is initialized
- * false - if the message queue is NOT initialized
- */
-
bool _CORE_message_queue_Initialize(
CORE_message_queue_Control *the_message_queue,
CORE_message_queue_Attributes *the_message_queue_attributes,
diff --git a/cpukit/score/src/coresem.c b/cpukit/score/src/coresem.c
index f0fa9f4..03b9c5e 100644
--- a/cpukit/score/src/coresem.c
+++ b/cpukit/score/src/coresem.c
@@ -1,12 +1,11 @@
-/*
- * CORE Semaphore Handler
- *
- * DESCRIPTION:
- *
- * This package is the implementation of the CORE Semaphore Handler.
- * This core object utilizes standard Dijkstra counting semaphores to provide
- * synchronization and mutual exclusion capabilities.
+/**
+ * @file
*
+ * @brief Core Semaphore Initialize
+ * @ingroup ScoreSemaphore
+ */
+
+/*
* COPYRIGHT (c) 1989-1999.
* On-Line Applications Research Corporation (OAR).
*
@@ -26,20 +25,6 @@
#include <rtems/score/thread.h>
#include <rtems/score/threadq.h>
-/*
- * CORE_semaphore_Initialize
- *
- * This function initialize a semaphore and sets the initial value based
- * on the given count.
- *
- * Input parameters:
- * the_semaphore - the semaphore control block to initialize
- * the_semaphore_attributes - the attributes specified at create time
- * initial_value - semaphore's initial value
- *
- * Output parameters: NONE
- */
-
void _CORE_semaphore_Initialize(
CORE_semaphore_Control *the_semaphore,
CORE_semaphore_Attributes *the_semaphore_attributes,
diff --git a/cpukit/score/src/coretodget.c b/cpukit/score/src/coretodget.c
index 448bc7b..dbee757 100644
--- a/cpukit/score/src/coretodget.c
+++ b/cpukit/score/src/coretodget.c
@@ -1,6 +1,11 @@
-/*
- * Time of Day (TOD) Handler - get TOD
+/**
+ * @file
*
+ * @brief Returns a Current TOD with Nanosecond Granularity
+ * @ingroup ScoreTODConstants
+ */
+
+/*
* COPYRIGHT (c) 1989-2008.
* On-Line Applications Research Corporation (OAR).
*
diff --git a/cpukit/score/src/coretodtickspersec.c b/cpukit/score/src/coretodtickspersec.c
index 21e7201..3dc792a 100644
--- a/cpukit/score/src/coretodtickspersec.c
+++ b/cpukit/score/src/coretodtickspersec.c
@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief Convert Ticks To Seconds
+ * @ingroup ScoreTODConstants
+ */
+
/* COPYRIGHT (c) 1989-2008.
* On-Line Applications Research Corporation (OAR).
*
diff --git a/cpukit/score/src/objectgetnoprotection.c b/cpukit/score/src/objectgetnoprotection.c
index 8d283ab..30b61cc 100644
--- a/cpukit/score/src/objectgetnoprotection.c
+++ b/cpukit/score/src/objectgetnoprotection.c
@@ -1,7 +1,11 @@
-/*
- * Object Handler -- Object Get
- *
+/**
+ * @file
*
+ * @brief Get Object without Dispatching Protection
+ * @ingroup ScoreObject
+ */
+
+/*
* COPYRIGHT (c) 1989-2002.
* On-Line Applications Research Corporation (OAR).
*
@@ -26,25 +30,6 @@
#include <rtems/score/sysstate.h>
#include <rtems/score/isr.h>
-/*
- * _Objects_Get_no_protection
- *
- * This routine sets the object pointer for the given
- * object id based on the given object information structure.
- *
- * Input parameters:
- * information - pointer to entry in table for this class
- * id - object id to search for
- * location - address of where to store the location
- *
- * Output parameters:
- * returns - address of object if local
- * location - one of the following:
- * OBJECTS_ERROR - invalid object ID
- * OBJECTS_REMOTE - remote object
- * OBJECTS_LOCAL - local object
- */
-
Objects_Control *_Objects_Get_no_protection(
Objects_Information *information,
Objects_Id id,
diff --git a/cpukit/score/src/schedulercbscleanup.c b/cpukit/score/src/schedulercbscleanup.c
index 392c995..abffeaf 100644
--- a/cpukit/score/src/schedulercbscleanup.c
+++ b/cpukit/score/src/schedulercbscleanup.c
@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief Scheduler CBS Cleanup
+ * @ingroup ScoreScheduler
+ */
+
/*
* Copyright (C) 2011 Petr Benes.
* Copyright (C) 2011 On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/score/src/schedulercbscreateserver.c b/cpukit/score/src/schedulercbscreateserver.c
index 2780a71..9f69fba 100644
--- a/cpukit/score/src/schedulercbscreateserver.c
+++ b/cpukit/score/src/schedulercbscreateserver.c
@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief Scheduler CBS Create Server
+ * @ingroup ScoreScheduler
+ */
+
/*
* Copyright (C) 2011 Petr Benes.
* Copyright (C) 2011 On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/score/src/schedulercbsgetapprovedbudget.c b/cpukit/score/src/schedulercbsgetapprovedbudget.c
index bf2877f..8558f87 100644
--- a/cpukit/score/src/schedulercbsgetapprovedbudget.c
+++ b/cpukit/score/src/schedulercbsgetapprovedbudget.c
@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief Scheduler CBS Get Approved Budget
+ * @ingroup ScoreScheduler
+ */
+
/*
* Copyright (C) 2011 Petr Benes.
* Copyright (C) 2011 On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/score/src/schedulercbsgetremainingbudget.c b/cpukit/score/src/schedulercbsgetremainingbudget.c
index 4e32181..2d79995 100644
--- a/cpukit/score/src/schedulercbsgetremainingbudget.c
+++ b/cpukit/score/src/schedulercbsgetremainingbudget.c
@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief Scheduler CBS Get Remaining Budget
+ * @ingroup ScoreScheduler
+ */
+
/*
* Copyright (C) 2011 Petr Benes.
* Copyright (C) 2011 On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/score/src/schedulerpriorityprioritycompare.c b/cpukit/score/src/schedulerpriorityprioritycompare.c
index 962adc4..7d37707 100644
--- a/cpukit/score/src/schedulerpriorityprioritycompare.c
+++ b/cpukit/score/src/schedulerpriorityprioritycompare.c
@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief Scheduler Priority Compare Two Priorities
+ * @ingroup ScoreScheduler
+ */
+
/*
* COPYRIGHT (c) 2011.
* On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/score/src/schedulerpriorityreleasejob.c b/cpukit/score/src/schedulerpriorityreleasejob.c
index 9c2864d..a62a10a 100644
--- a/cpukit/score/src/schedulerpriorityreleasejob.c
+++ b/cpukit/score/src/schedulerpriorityreleasejob.c
@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief Scheduler Priority Release Job
+ * @ingroup ScoreScheduler
+ */
+
/*
* Copyright (C) 2011 Petr Benes.
* Copyright (C) 2011 On-Line Applications Research Corporation (OAR).
diff --git a/cpukit/score/src/schedulerpriorityunblock.c b/cpukit/score/src/schedulerpriorityunblock.c
index 4a45877..f1d52e3 100644
--- a/cpukit/score/src/schedulerpriorityunblock.c
+++ b/cpukit/score/src/schedulerpriorityunblock.c
@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief Scheduler Priority Unblock
+ * @ingroup ScoreScheduler
+ */
+
/*
* Scheduler Handler
*
diff --git a/cpukit/score/src/schedulersimpleenqueuefirst.c b/cpukit/score/src/schedulersimpleenqueuefirst.c
index 4f562a4..354bbc7 100644
--- a/cpukit/score/src/schedulersimpleenqueuefirst.c
+++ b/cpukit/score/src/schedulersimpleenqueuefirst.c
@@ -1,6 +1,11 @@
-/*
- * Schedule Simple Handler / Enqueue First
+/**
+ * @file
*
+ * @brief Scheduler Simple Enqueue First
+ * @ingroup ScoreScheduler
+ */
+
+/*
* COPYRIGHT (c) 2011.
* On-Line Applications Research Corporation (OAR).
*
diff --git a/cpukit/score/src/smplock.c b/cpukit/score/src/smplock.c
index 9ef4e07..89f8a86 100644
--- a/cpukit/score/src/smplock.c
+++ b/cpukit/score/src/smplock.c
@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief SMP Locking Support
+ * @ingroup RTEMS
+ */
+
/*
* COPYRIGHT (c) 1989-2011.
* On-Line Applications Research Corporation (OAR).
@@ -67,9 +74,6 @@
#define debug_dump_log()
#endif
-/*
- * SMP spinlock simple methods
- */
void _SMP_lock_spinlock_simple_Initialize(
SMP_lock_spinlock_simple_Control *lock
)
@@ -105,9 +109,6 @@ void _SMP_lock_spinlock_simple_Release(
_ISR_Enable_on_this_core( level );
}
-/*
- * SMP spinlock nested methods.
- */
void _SMP_lock_spinlock_nested_Initialize(
SMP_lock_spinlock_nested_Control *lock
)
diff --git a/cpukit/score/src/threadqenqueuefifo.c b/cpukit/score/src/threadqenqueuefifo.c
index b873ba0..ab1404c 100644
--- a/cpukit/score/src/threadqenqueuefifo.c
+++ b/cpukit/score/src/threadqenqueuefifo.c
@@ -1,7 +1,11 @@
-/*
- * Thread Queue Handler
- *
+/**
+ * @file
*
+ * @brief Thread queue Enqueue FIFO
+ * @ingroup ScoreThreadQ
+ */
+
+/*
* COPYRIGHT (c) 1989-2008.
* On-Line Applications Research Corporation (OAR).
*
@@ -23,21 +27,6 @@
#include <rtems/score/threadq.h>
#include <rtems/score/tqdata.h>
-/*
- * _Thread_queue_Enqueue_fifo
- *
- * This routine places a blocked thread on a FIFO thread queue.
- *
- * Input parameters:
- * the_thread_queue - pointer to threadq
- * the_thread - pointer to the thread to block
- *
- * Output parameters: NONE
- *
- * INTERRUPT LATENCY:
- * only case
- */
-
Thread_blocking_operation_States _Thread_queue_Enqueue_fifo (
Thread_queue_Control *the_thread_queue,
Thread_Control *the_thread,
diff --git a/cpukit/score/src/threadqrequeue.c b/cpukit/score/src/threadqrequeue.c
index 769f709..15cf011 100644
--- a/cpukit/score/src/threadqrequeue.c
+++ b/cpukit/score/src/threadqrequeue.c
@@ -1,7 +1,11 @@
-/*
- * Thread Queue Handler
- *
+/**
+ * @file
*
+ * @brief Thread Queue Requeue
+ * @ingroup ScoreThreadQ
+ */
+
+/*
* COPYRIGHT (c) 1989-2008.
* On-Line Applications Research Corporation (OAR).
*
@@ -23,21 +27,6 @@
#include <rtems/score/threadq.h>
#include <rtems/score/tqdata.h>
-/*
- * _Thread_queue_Requeue
- *
- * This routine is invoked when a thread changes priority and should be
- * moved to a different position on the thread queue.
- *
- * Input parameters:
- * the_thread_queue - pointer to a threadq header
- * the_thread - pointer to a thread control block
- *
- * Output parameters: NONE
- *
- * INTERRUPT LATENCY: NONE
- */
-
void _Thread_queue_Requeue(
Thread_queue_Control *the_thread_queue,
Thread_Control *the_thread
diff --git a/cpukit/score/src/threadsetpriority.c b/cpukit/score/src/threadsetpriority.c
index a500624..1ae4a27 100644
--- a/cpukit/score/src/threadsetpriority.c
+++ b/cpukit/score/src/threadsetpriority.c
@@ -1,6 +1,11 @@
-/*
- * Thread Handler / Thread Set Priority
+/**
+ * @file
*
+ * @brief Set Thread Priority
+ * @ingroup ScoreThread
+ */
+
+/*
* COPYRIGHT (c) 1989-2011.
* On-Line Applications Research Corporation (OAR).
*
diff --git a/cpukit/score/src/ts64dividebyinteger.c b/cpukit/score/src/ts64dividebyinteger.c
index b48c188..55dc816 100644
--- a/cpukit/score/src/ts64dividebyinteger.c
+++ b/cpukit/score/src/ts64dividebyinteger.c
@@ -1,6 +1,9 @@
/**
- * @file score/src/ts64dividebyinteger.c
-*/
+ * @file
+ *
+ * @brief Divide Timestamp By Integer
+ * @ingroup SuperCore
+ */
/*
* COPYRIGHT (c) 1989-2008.
diff --git a/cpukit/score/src/watchdogadjust.c b/cpukit/score/src/watchdogadjust.c
index 5dc4b31..b0723d0 100644
--- a/cpukit/score/src/watchdogadjust.c
+++ b/cpukit/score/src/watchdogadjust.c
@@ -1,7 +1,11 @@
-/*
- * Watchdog Handler
- *
+/**
+ * @file
*
+ * @brief Watchdog Adjust
+ * @ingroup ScoreWatchdog
+ */
+
+/*
* COPYRIGHT (c) 1989-1999.
* On-Line Applications Research Corporation (OAR).
*
@@ -18,20 +22,6 @@
#include <rtems/score/isr.h>
#include <rtems/score/watchdog.h>
-/*
- * _Watchdog_Adjust
- *
- * This routine adjusts the delta chain backward or forward in response
- * to a time change.
- *
- * Input parameters:
- * header - pointer to the delta chain to be adjusted
- * direction - forward or backward adjustment to delta chain
- * units - units to adjust
- *
- * Output parameters:
- */
-
void _Watchdog_Adjust(
Chain_Control *header,
Watchdog_Adjust_directions direction,
More information about the vc
mailing list