[rtems commit] rtems misc: Clean up Doxygen GCI Task #7

Gedare Bloom gedare at rtems.org
Wed Dec 5 23:12:33 UTC 2012


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

Author:    Alex Ivanov <alexivanov97 at gmail.com>
Date:      Wed Dec  5 18:16:48 2012 -0500

rtems misc: Clean up Doxygen GCI Task #7

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

---

 cpukit/rtems/include/rtems/rtems/clock.h      |    4 ++-
 cpukit/rtems/include/rtems/rtems/dpmem.h      |   13 +++++++-
 cpukit/rtems/include/rtems/rtems/message.h    |   14 ++++++++-
 cpukit/rtems/include/rtems/rtems/part.h       |   11 ++++++-
 cpukit/rtems/include/rtems/rtems/ratemon.h    |   34 +++++++++++++++++++--
 cpukit/rtems/include/rtems/rtems/region.h     |   13 +++++++-
 cpukit/rtems/include/rtems/rtems/sem.h        |   10 ++++++-
 cpukit/rtems/include/rtems/rtems/support.h    |    6 ++--
 cpukit/rtems/include/rtems/rtems/tasks.h      |   11 ++++++-
 cpukit/rtems/include/rtems/rtems/timer.h      |   19 +++++++++++-
 cpukit/rtems/src/clockgettickssinceboot.c     |    9 ++++-
 cpukit/rtems/src/clocktodvalidate.c           |   25 ++++------------
 cpukit/rtems/src/dpmeminternal2external.c     |   27 ++++-------------
 cpukit/rtems/src/msgqreceive.c                |   28 ++++-------------
 cpukit/rtems/src/partdelete.c                 |   25 ++++------------
 cpukit/rtems/src/ratemon.c                    |   24 ++++-----------
 cpukit/rtems/src/ratemondelete.c              |   22 ++++----------
 cpukit/rtems/src/ratemongetstatus.c           |   25 ++++------------
 cpukit/rtems/src/ratemonident.c               |   25 ++++------------
 cpukit/rtems/src/ratemonreportstatistics.c    |   17 ++++------
 cpukit/rtems/src/regiongetfreeinfo.c          |   27 ++++-------------
 cpukit/rtems/src/rtemsobjectapimaximumclass.c |    9 ++++-
 cpukit/rtems/src/rtemsobjectgetapiname.c      |    9 ++++-
 cpukit/rtems/src/semobtain.c                  |   38 ++++--------------------
 cpukit/rtems/src/taskmode.c                   |   25 ++++------------
 cpukit/rtems/src/taskvariableadd.c            |   16 ++++------
 cpukit/rtems/src/timerdelete.c                |   23 ++++----------
 cpukit/rtems/src/timerfireafter.c             |   26 ++++------------
 cpukit/rtems/src/workspace.c                  |   15 ++++-----
 29 files changed, 247 insertions(+), 303 deletions(-)

diff --git a/cpukit/rtems/include/rtems/rtems/clock.h b/cpukit/rtems/include/rtems/rtems/clock.h
index c841d1a..fc6a584 100644
--- a/cpukit/rtems/include/rtems/rtems/clock.h
+++ b/cpukit/rtems/include/rtems/rtems/clock.h
@@ -243,7 +243,7 @@ void rtems_clock_get_uptime_timeval( struct timeval *uptime );
 time_t rtems_clock_get_uptime_seconds( void );
 
 /**
- *  @brief _TOD_Validate
+ *  @brief TOD Validate
  *
  *  This support function returns true if @a the_tod contains
  *  a valid time of day, and false otherwise.
@@ -251,6 +251,8 @@ time_t rtems_clock_get_uptime_seconds( void );
  *  @param[in] the_tod is the TOD structure to validate
  *
  *  @return This method returns true if the TOD is valid and false otherwise.
+ * 
+ *  @note This routine only works for leap-years through 2099.
  */
 bool _TOD_Validate(
   const rtems_time_of_day *the_tod
diff --git a/cpukit/rtems/include/rtems/rtems/dpmem.h b/cpukit/rtems/include/rtems/rtems/dpmem.h
index e305b31..5186fa1 100644
--- a/cpukit/rtems/include/rtems/rtems/dpmem.h
+++ b/cpukit/rtems/include/rtems/rtems/dpmem.h
@@ -166,11 +166,20 @@ rtems_status_code rtems_port_external_to_internal(
 );
 
 /**
- *  @brief rtems_port_internal_to_external
+ *  @brief RTEMS Port Internal to External
  *
  *  This routine implements the Port_internal_to_external directive.
  *  It returns the external port address which maps to the provided
- *  internal port address for the specified port ID.
+ *  internal port address for the specified port ID.  If the given
+ *  internal address is an invalid dual-ported address, then the
+ *  external address is set to the given internal address.
+ * 
+ *  @param[in] id is the id of dual-ported memory object
+ *  @param[in] internal is the internal address to set
+ *  @param[in] external is the pointer to external address
+ * 
+ *  @return RTEMS_SUCCESSFUL and the external will be filled in 
+ *  with the external addresses
  */
 rtems_status_code rtems_port_internal_to_external(
   rtems_id     id,
diff --git a/cpukit/rtems/include/rtems/rtems/message.h b/cpukit/rtems/include/rtems/rtems/message.h
index 9990b14..10da602 100644
--- a/cpukit/rtems/include/rtems/rtems/message.h
+++ b/cpukit/rtems/include/rtems/rtems/message.h
@@ -234,7 +234,7 @@ rtems_status_code rtems_message_queue_broadcast(
 );
 
 /**
- *  @brief rtems_message_queue_receive
+ *  @brief RTEMS Message Queue Receive
  *
  *  This routine implements the rtems_message_queue_receive directive.
  *  This directive is invoked when the calling task wishes to receive
@@ -242,7 +242,17 @@ rtems_status_code rtems_message_queue_broadcast(
  *  message is to be placed in buffer.  If no messages are outstanding
  *  and the option_set indicates that the task is willing to block,
  *  then the task will be blocked until a message arrives or until,
- *  optionally, timeout clock ticks have passed.
+ *  optionally, timeout clock ticks have passed. 
+ * 
+ *  @param[in] id is the queue id
+ *  @param[in] buffer is the pointer to message buffer
+ *  @param[in] size is the size of message receive
+ *  @param[in] option_set is the options on receive
+ *  @param[in] timeout is the number of ticks to wait
+ * 
+ *  @return This method returns RTEMS_SUCCESSFUL if there was not an
+ *          error.  Otherwise, a status code is returned indicating the
+ *          source of the error.
  */
 rtems_status_code rtems_message_queue_receive(
   rtems_id        id,
diff --git a/cpukit/rtems/include/rtems/rtems/part.h b/cpukit/rtems/include/rtems/rtems/part.h
index d46be0a..ebdc845 100644
--- a/cpukit/rtems/include/rtems/rtems/part.h
+++ b/cpukit/rtems/include/rtems/rtems/part.h
@@ -135,10 +135,17 @@ rtems_status_code rtems_partition_ident(
 );
 
 /**
- *  @brief rtems_partition_delete
+ *  @brief RTEMS Delete Partition
  *
  *  This routine implements the rtems_partition_delete directive.  The
- *  partition indicated by ID is deleted.
+ *  partition indicated by ID is deleted, provided that none of its buffers
+ *  are still allocated.
+ * 
+ *  @param[in] id is the partition id
+ * 
+ *  @return This method returns RTEMS_SUCCESSFUL if there was not an
+ *          error.  Otherwise, a status code is returned indicating the
+ *          source of the error.
  */
 rtems_status_code rtems_partition_delete(
   rtems_id id
diff --git a/cpukit/rtems/include/rtems/rtems/ratemon.h b/cpukit/rtems/include/rtems/rtems/ratemon.h
index 93c8e26..9b0d1de 100644
--- a/cpukit/rtems/include/rtems/rtems/ratemon.h
+++ b/cpukit/rtems/include/rtems/rtems/ratemon.h
@@ -269,6 +269,8 @@ RTEMS_RATEMON_EXTERN Objects_Information _Rate_monotonic_Information;
  *  @brief Rate Monotonic Manager Initialization
  *
  *  This routine performs the initialization necessary for this manager.
+ * 
+ *  @note The Rate Monotonic Manager is built on top of the Watchdog Handler
  */
 void _Rate_monotonic_Manager_initialization(void);
 
@@ -285,11 +287,19 @@ rtems_status_code rtems_rate_monotonic_create(
 );
 
 /**
- *  @brief rtems_rate_monotonic_ident
+ *  @brief RTEMS Rate Monotonic Name to Id
  *
  *  This routine implements the rtems_rate_monotonic_ident directive.
  *  It returns the period ID associated with name.  If more than one period
  *  is named name, then the period to which the ID belongs is arbitrary.
+ * 
+ *  @param[in] name is the user defined period name
+ *  @param[in] id is the pointer to period id
+ * 
+ *  @return This method returns RTEMS_SUCCESSFUL if there was not an
+ *          error.  Otherwise, a status code is returned indicating the
+ *          source of the error.  If successful, the id will
+ *          be filled in with the region id.
  */
 rtems_status_code rtems_rate_monotonic_ident(
   rtems_name    name,
@@ -314,10 +324,16 @@ rtems_status_code rtems_rate_monotonic_cancel(
 );
 
 /**
- *  @brief rtems_rate_monotonic_delete
+ *  @brief RTEMS Delete Rate Monotonic
  *
  *  This routine implements the rtems_rate_monotonic_delete directive.  The
  *  period indicated by ID is deleted.
+ * 
+ *  @param[in] id is the rate monotonic id
+ * 
+ *  @return This method returns RTEMS_SUCCESSFUL if there was not an
+ *          error.  Otherwise, a status code is returned indicating the
+ *          source of the error.
  */
 rtems_status_code rtems_rate_monotonic_delete(
   rtems_id   id
@@ -328,6 +344,13 @@ rtems_status_code rtems_rate_monotonic_delete(
  *
  *  This routine implements the rtems_rate_monotonic_get_status directive.
  *  Information about the period indicated by ID is returned.
+ * 
+ *  @param[in] id is the rate monotonic id
+ *  @param[in] status is the pointer to status control block
+ * 
+ *  @return This method returns RTEMS_SUCCESSFUL if there was not an
+ *          error.  Otherwise, a status code is returned indicating the
+ *          source of the error.
  *
  */
 rtems_status_code rtems_rate_monotonic_get_status(
@@ -370,10 +393,13 @@ rtems_status_code rtems_rate_monotonic_reset_statistics(
 void rtems_rate_monotonic_reset_all_statistics( void );
 
 /**
- *  @brief rtems_rate_monotonic_report_statistics
+ *  @brief RTEMS Report Rate Monotonic Statistics
  *
  *  This routine allows a thread to print the statistics information
  *  on ALL period instances which have non-zero counts using printk.
+ *  The implementation of this directive straddles the fence between
+ *  inside and outside of RTEMS.  It is presented as part of the Manager
+ *  but actually uses other services of the Manager.
  */
 void rtems_rate_monotonic_report_statistics_with_plugin(
   void                  *context,
@@ -381,7 +407,7 @@ void rtems_rate_monotonic_report_statistics_with_plugin(
 );
 
 /**
- *  @brief rtems_rate_monotonic_report_statistics
+ *  @brief RTEMS Report Rate Monotonic Statistics
  *
  *  This routine allows a thread to print the statistics information
  *  on ALL period instances which have non-zero counts using printk.
diff --git a/cpukit/rtems/include/rtems/rtems/region.h b/cpukit/rtems/include/rtems/rtems/region.h
index f58bdff..b183b9d 100644
--- a/cpukit/rtems/include/rtems/rtems/region.h
+++ b/cpukit/rtems/include/rtems/rtems/region.h
@@ -170,11 +170,20 @@ rtems_status_code rtems_region_get_information(
 );
 
 /**
- *  @brief rtems_region_get_free_information
+ *  @brief RTEMS Get Region Free Information
  *
  *  This routine implements the rtems_region_get_free_information directive.
  *  This directive returns information about the free blocks in the
- *  heap associated with this region.
+ *  heap associated with this region.  Information about the used blocks
+ *  will be returned as zero.
+ * 
+ *  @param[in] id is the region id
+ *  @param[in] the_info is the pointer to region information block
+ * 
+ *  @return This method returns RTEMS_SUCCESSFUL if there was not an
+ *          error.  Otherwise, a status code is returned indicating the
+ *          source of the error.  If successful, the the_info will
+ *          be filled in with the region information block.
  */
 rtems_status_code rtems_region_get_free_information(
   rtems_id                id,
diff --git a/cpukit/rtems/include/rtems/rtems/sem.h b/cpukit/rtems/include/rtems/rtems/sem.h
index aedc5ea..4fcf93e 100644
--- a/cpukit/rtems/include/rtems/rtems/sem.h
+++ b/cpukit/rtems/include/rtems/rtems/sem.h
@@ -168,7 +168,7 @@ rtems_status_code rtems_semaphore_delete(
 );
 
 /**
- *  @brief rtems_semaphore_obtain
+ *  @brief RTEMS Obtain Semaphore
  *
  *  This routine implements the rtems_semaphore_obtain directive.  It
  *  attempts to obtain a unit from the semaphore associated with ID.
@@ -177,6 +177,14 @@ rtems_status_code rtems_semaphore_delete(
  *  block waiting for a unit with an optional timeout of timeout
  *  clock ticks.  Whether the task blocks or returns immediately
  *  is based on the RTEMS_NO_WAIT option in the option_set.
+ * 
+ *  @param[in] id is the semaphore id
+ *  @param[in] option_set is the wait option
+ *  @param[in] timeout is the number of ticks to wait (0 means wait forever)
+ * 
+ *  @return This method returns RTEMS_SUCCESSFUL if there was not an
+ *          error.  Otherwise, a status code is returned indicating the
+ *          source of the error.
  */
 rtems_status_code rtems_semaphore_obtain(
   rtems_id       id,
diff --git a/cpukit/rtems/include/rtems/rtems/support.h b/cpukit/rtems/include/rtems/rtems/support.h
index 99bf405..30716de 100644
--- a/cpukit/rtems/include/rtems/rtems/support.h
+++ b/cpukit/rtems/include/rtems/rtems/support.h
@@ -63,7 +63,7 @@ extern "C" {
  */
 
 /**
- * @brief Gets workspace information.
+ * @brief Gets Workspace Information
  *
  * Returns information about the heap that is used as the RTEMS Executive
  * Workspace in @a the_info.
@@ -75,7 +75,7 @@ bool rtems_workspace_get_information(
 );
 
 /**
- * @brief Allocates memory from the workspace.
+ * @brief Allocates Memory from the Workspace
  *
  * A number of @a bytes bytes will be allocated from the RTEMS Executive
  * Workspace and returned in @a pointer.
@@ -88,7 +88,7 @@ bool rtems_workspace_allocate(
 );
 
 /**
- * @brief Frees memory allocated from the workspace.
+ * @brief Frees Memory Allocated from the Workspace
  *
  * This frees the memory indicated by @a pointer that was allocated from the
  * RTEMS Executive Workspace.
diff --git a/cpukit/rtems/include/rtems/rtems/tasks.h b/cpukit/rtems/include/rtems/rtems/tasks.h
index abd7d1f..7ec65a9 100644
--- a/cpukit/rtems/include/rtems/rtems/tasks.h
+++ b/cpukit/rtems/include/rtems/rtems/tasks.h
@@ -362,12 +362,19 @@ rtems_status_code rtems_task_set_note(
 );
 
 /**
- *  @brief rtems_task_mode
+ *  @brief RTEMS Task Mode
  *
  *  This routine implements the rtems_task_mode directive.  The current
  *  values of the modes indicated by mask of the calling task are changed
  *  to that indicated in mode_set.  The former mode of the task is
  *  returned in mode_set.
+ * 
+ *  @param[in] mode_set is the new mode
+ *  @param[in] mask is the mask
+ *  @param[in] previous_mode_set is the address of previous mode set
+ * 
+ *  @return RTEMS_SUCCESSFUL and previous_mode_set filled in with the 
+ *  previous mode set
  */
 rtems_status_code rtems_task_mode(
   rtems_mode  mode_set,
@@ -499,7 +506,7 @@ rtems_status_code rtems_task_is_suspended(
 );
 
 /**
- *  @brief rtems_task_variable_add
+ *  @brief RTEMS Add Task Variable
  *
  *  This directive adds a per task variable.
  */
diff --git a/cpukit/rtems/include/rtems/rtems/timer.h b/cpukit/rtems/include/rtems/rtems/timer.h
index b7ab2e2..5a908eb 100644
--- a/cpukit/rtems/include/rtems/rtems/timer.h
+++ b/cpukit/rtems/include/rtems/rtems/timer.h
@@ -275,23 +275,38 @@ rtems_status_code rtems_timer_cancel(
 );
 
 /**
- *  @brief rtems_timer_delete
+ *  @brief RTEMS Delete Timer
  *
  *  This routine implements the rtems_timer_delete directive.  The
  *  timer indicated by ID is deleted.
+ * 
+ *  @param[in] id is the timer id
+ * 
+ *  @return This method returns RTEMS_SUCCESSFUL if there was not an
+ *          error.  Otherwise, a status code is returned indicating the
+ *          source of the error.
  */
 rtems_status_code rtems_timer_delete(
   rtems_id   id
 );
 
 /**
- *  @brief rtems_timer_fire_after
+ *  @brief RTEMS Timer Fire After
  *
  *  This routine implements the rtems_timer_fire_after directive.  It
  *  initiates the timer associated with ID to fire in ticks clock ticks.
  *  When the timer fires, the routine will be invoked in the context
  *  of the rtems_clock_tick directive which is normally invoked as
  *  part of servicing a periodic interupt.
+ * 
+ *  @param[in] id is the timer id
+ *  @param[in] ticks is the interval until routine is fired
+ *  @param[in] routine is the routine to schedule
+ *  @param[in] user_data is the passed as argument to routine when it is fired
+ * 
+ *  @return This method returns RTEMS_SUCCESSFUL if there was not an
+ *          error.  Otherwise, a status code is returned indicating the
+ *          source of the error.
  */
 rtems_status_code rtems_timer_fire_after(
   rtems_id                           id,
diff --git a/cpukit/rtems/src/clockgettickssinceboot.c b/cpukit/rtems/src/clockgettickssinceboot.c
index 96a1c5e..cfd91b5 100644
--- a/cpukit/rtems/src/clockgettickssinceboot.c
+++ b/cpukit/rtems/src/clockgettickssinceboot.c
@@ -1,6 +1,11 @@
-/*
- *  Clock Manager - Get Ticks Since Boot
+/**
+ *  @file
  *
+ *  @brief Obtain Ticks Since Boot
+ *  @ingroup ClassicClock
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/rtems/src/clocktodvalidate.c b/cpukit/rtems/src/clocktodvalidate.c
index 7aa854c..a56b1df 100644
--- a/cpukit/rtems/src/clocktodvalidate.c
+++ b/cpukit/rtems/src/clocktodvalidate.c
@@ -1,7 +1,11 @@
-/*
- *  Time of Day (TOD) Handler -- Validate Classic TOD
- *
+/**
+ *  @file
  *
+ *  @brief TOD Validate
+ *  @ingroup ClassicClock
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -29,21 +33,6 @@ const uint32_t   _TOD_Days_per_month[ 2 ][ 13 ] = {
   { 0, 31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31 }
 };
 
-/*
- *  _TOD_Validate
- *
- *  This kernel routine checks the validity of a date and time structure.
- *
- *  Input parameters:
- *    the_tod - pointer to a time and date structure
- *
- *  Output parameters:
- *    true  - if the date, time, and tick are valid
- *    false - if the the_tod is invalid
- *
- *  NOTE: This routine only works for leap-years through 2099.
- */
-
 bool _TOD_Validate(
   const rtems_time_of_day *the_tod
 )
diff --git a/cpukit/rtems/src/dpmeminternal2external.c b/cpukit/rtems/src/dpmeminternal2external.c
index 6e61566..a6c8d83 100644
--- a/cpukit/rtems/src/dpmeminternal2external.c
+++ b/cpukit/rtems/src/dpmeminternal2external.c
@@ -1,6 +1,11 @@
-/*
- *  Dual Port Memory Manager
+/**
+ *  @file
  *
+ *  @brief RTEMS Port Internal to External
+ *  @ingroup ClassicDPMEM
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -22,24 +27,6 @@
 #include <rtems/score/thread.h>
 #include <rtems/rtems/dpmem.h>
 
-/*
- *  rtems_port_internal_to_external
- *
- *  This directive converts an internal dual-ported memory address to an
- *  external dual-ported memory address.  If the given internal address
- *  is an invalid dual-ported address, then the external address is set
- *  to the given internal address.
- *
- *  Input parameters:
- *    id       - id of dual-ported memory object
- *    internal - internal address to set
- *    external - pointer to external address
- *
- *  Output parameters:
- *    external          - external address
- *    RTEMS_SUCCESSFUL - always succeeds
- */
-
 rtems_status_code rtems_port_internal_to_external(
   rtems_id   id,
   void      *internal,
diff --git a/cpukit/rtems/src/msgqreceive.c b/cpukit/rtems/src/msgqreceive.c
index 00ed6c2..6be06ad 100644
--- a/cpukit/rtems/src/msgqreceive.c
+++ b/cpukit/rtems/src/msgqreceive.c
@@ -1,7 +1,11 @@
-/*
- *  Message Queue Manager
- *
+/**
+ *  @file
  *
+ *  @brief RTEMS Message Queue Receive
+ *  @ingroup ClassicMessageQueue
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -32,24 +36,6 @@
 #include <rtems/rtems/options.h>
 #include <rtems/rtems/support.h>
 
-/*
- *  rtems_message_queue_receive
- *
- *  This directive dequeues a message from the designated message queue
- *  and copies it into the requesting thread's buffer.
- *
- *  Input parameters:
- *    id         - queue id
- *    buffer     - pointer to message buffer
- *    size       - size of message receive
- *    option_set - options on receive
- *    timeout    - number of ticks to wait
- *
- *  Output parameters:
- *    RTEMS_SUCCESSFUL - if successful
- *    error code       - if unsuccessful
- */
-
 rtems_status_code rtems_message_queue_receive(
   rtems_id        id,
   void           *buffer,
diff --git a/cpukit/rtems/src/partdelete.c b/cpukit/rtems/src/partdelete.c
index 6cae308..6aeee4e 100644
--- a/cpukit/rtems/src/partdelete.c
+++ b/cpukit/rtems/src/partdelete.c
@@ -1,7 +1,11 @@
-/*
- *  Partition Manager
- *
+/**
+ *  @file
  *
+ *  @brief RTEMS Delete Partition
+ *  @ingroup ClassicPart
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -23,21 +27,6 @@
 #include <rtems/score/thread.h>
 #include <rtems/score/sysstate.h>
 
-/*
- *  rtems_partition_delete
- *
- *  This directive allows a thread to delete a partition specified by
- *  the partition identifier, provided that none of its buffers are
- *  still allocated.
- *
- *  Input parameters:
- *    id - partition id
- *
- *  Output parameters:
- *    RTEMS_SUCCESSFUL - if successful
- *    error code       - if unsuccessful
- */
-
 rtems_status_code rtems_partition_delete(
   rtems_id id
 )
diff --git a/cpukit/rtems/src/ratemon.c b/cpukit/rtems/src/ratemon.c
index d2eba80..d96a9b0 100644
--- a/cpukit/rtems/src/ratemon.c
+++ b/cpukit/rtems/src/ratemon.c
@@ -1,7 +1,11 @@
-/*
- *  Rate Monotonic Manager
- *
+/**
+ *  @file
  *
+ *  @brief Rate Monotonic Manager Initialization
+ *  @ingroup ClassicRateMon
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -23,20 +27,6 @@
 #include <rtems/rtems/ratemon.h>
 #include <rtems/score/thread.h>
 
-/*
- *  _Rate_monotonic_Manager_initialization
- *
- *  This routine initializes all Rate Monotonic Manager related
- *  data structures.
- *
- *  Input parameters:   NONE
- *
- *  Output parameters:  NONE
- *
- *  NOTE: The Rate Monotonic Manager is built on top of the Watchdog
- *        Handler.
- */
-
 void _Rate_monotonic_Manager_initialization(void)
 {
   _Objects_Initialize_information(
diff --git a/cpukit/rtems/src/ratemondelete.c b/cpukit/rtems/src/ratemondelete.c
index 751c7f5..15498ea 100644
--- a/cpukit/rtems/src/ratemondelete.c
+++ b/cpukit/rtems/src/ratemondelete.c
@@ -1,6 +1,11 @@
-/*
- *  Rate Monotonic Manager -- Delete a Period
+/**
+ *  @file
  *
+ *  @brief RTEMS Delete Rate Monotonic
+ *  @ingroup ClassicRateMon
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -21,19 +26,6 @@
 #include <rtems/rtems/ratemon.h>
 #include <rtems/score/thread.h>
 
-/*
- *  rtems_rate_monotonic_delete
- *
- *  This directive allows a thread to delete a rate monotonic timer.
- *
- *  Input parameters:
- *    id - rate monotonic id
- *
- *  Output parameters:
- *    RTEMS_SUCCESSFUL - if successful
- *    error code       - if unsuccessful
- */
-
 rtems_status_code rtems_rate_monotonic_delete(
   rtems_id id
 )
diff --git a/cpukit/rtems/src/ratemongetstatus.c b/cpukit/rtems/src/ratemongetstatus.c
index 73c59ee..5d0d584 100644
--- a/cpukit/rtems/src/ratemongetstatus.c
+++ b/cpukit/rtems/src/ratemongetstatus.c
@@ -1,6 +1,11 @@
-/*
- *  Rate Monotonic Manager -- Get Status
+/**
+ *  @file
  *
+ *  @brief RTEMS Rate Monotonic Get Status
+ *  @ingroup ClassicRateMon
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2009.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -25,22 +30,6 @@
   #include <rtems/score/timespec.h>
 #endif
 
-/*
- *  rtems_rate_monotonic_get_status
- *
- *  This directive allows a thread to obtain status information on a
- *  period.
- *
- *  Input parameters:
- *    id     - rate monotonic id
- *    status - pointer to status control block
- *
- *  Output parameters:
- *    RTEMS_SUCCESSFUL - if successful
- *    error code       - if unsuccessful
- *
- */
-
 rtems_status_code rtems_rate_monotonic_get_status(
   rtems_id                            id,
   rtems_rate_monotonic_period_status *status
diff --git a/cpukit/rtems/src/ratemonident.c b/cpukit/rtems/src/ratemonident.c
index 35e4195..def9580 100644
--- a/cpukit/rtems/src/ratemonident.c
+++ b/cpukit/rtems/src/ratemonident.c
@@ -1,6 +1,11 @@
-/*
- *  Rate Monotonic Manager -- Name to Id Lookup
+/**
+ *  @file
  *
+ *  @brief RTEMS Rate Monotonic Name to Id
+ *  @ingroup ClassicRateMon
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -21,22 +26,6 @@
 #include <rtems/rtems/ratemon.h>
 #include <rtems/score/thread.h>
 
-/*
- *  rtems_rate_monotonic_ident
- *
- *  This directive returns the system ID associated with
- *  the rate monotonic period name.
- *
- *  Input parameters:
- *    name - user defined period name
- *    id   - pointer to period id
- *
- *  Output parameters:
- *    *id              - region id
- *    RTEMS_SUCCESSFUL - if successful
- *    error code       - if unsuccessful
- */
-
 rtems_status_code rtems_rate_monotonic_ident(
   rtems_name  name,
   rtems_id   *id
diff --git a/cpukit/rtems/src/ratemonreportstatistics.c b/cpukit/rtems/src/ratemonreportstatistics.c
index c94171c..daf5fb5 100644
--- a/cpukit/rtems/src/ratemonreportstatistics.c
+++ b/cpukit/rtems/src/ratemonreportstatistics.c
@@ -1,6 +1,11 @@
-/*
- *  Rate Monotonic Manager -- Report Statistics for All Periods
+/**
+ *  @file
  *
+ *  @brief RTEMS Report Rate Monotonic Statistics
+ *  @ingroup ClassicRateMon
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2010.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -28,14 +33,6 @@
   #define NANOSECONDS_FMT "%06" PRId32
 #endif
 
-/*
- *  This directive allows a thread to print the statistics information
- *  on ALL period instances which have non-zero counts using printk.
- *
- *  The implementation of this directive straddles the fence between
- *  inside and outside of RTEMS.  It is presented as part of the Manager
- *  but actually uses other services of the Manager.
- */
 void rtems_rate_monotonic_report_statistics_with_plugin(
   void                  *context,
   rtems_printk_plugin_t  print
diff --git a/cpukit/rtems/src/regiongetfreeinfo.c b/cpukit/rtems/src/regiongetfreeinfo.c
index 52b7135..bd16b0e 100644
--- a/cpukit/rtems/src/regiongetfreeinfo.c
+++ b/cpukit/rtems/src/regiongetfreeinfo.c
@@ -1,7 +1,11 @@
-/*
- *  Region Manager
- *
+/**
+ *  @file
  *
+ *  @brief RTEMS Get Region Free Information
+ *  @ingroup ClassicRegion
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -24,23 +28,6 @@
 #include <rtems/score/apimutex.h>
 #include <rtems/score/thread.h>
 
-/*
- *  rtems_region_get_free_information
- *
- *  This directive will return information about the free blocks
- *  in the region specified.  Information about the used blocks
- *  will be returned as zero.
- *
- *  Input parameters:
- *    id         - region id
- *    the_info   - pointer to region information block
- *
- *  Output parameters:
- *    *the_info   - region information block filled in
- *    RTEMS_SUCCESSFUL - if successful
- *    error code - if unsuccessful
- */
-
 rtems_status_code rtems_region_get_free_information(
   rtems_id                id,
   Heap_Information_block *the_info
diff --git a/cpukit/rtems/src/rtemsobjectapimaximumclass.c b/cpukit/rtems/src/rtemsobjectapimaximumclass.c
index 17ad518..abeee03 100644
--- a/cpukit/rtems/src/rtemsobjectapimaximumclass.c
+++ b/cpukit/rtems/src/rtemsobjectapimaximumclass.c
@@ -1,6 +1,11 @@
-/*
- *  RTEMS Object Helper -- Get Greatest Valid Class for an API
+/**
+ *  @file
  *
+ *  @brief Get Highest Valid Class Value
+ *  @ingroup ClassicClassInfo
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/rtems/src/rtemsobjectgetapiname.c b/cpukit/rtems/src/rtemsobjectgetapiname.c
index 4976a92..2f10ce7 100644
--- a/cpukit/rtems/src/rtemsobjectgetapiname.c
+++ b/cpukit/rtems/src/rtemsobjectgetapiname.c
@@ -1,6 +1,11 @@
-/*
- *  RTEMS Object Helper -- Obtain Name of API
+/**
+ *  @file
  *
+ *  @brief Get API Name
+ *  @ingroup ClassicClassInfo
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
  *
diff --git a/cpukit/rtems/src/semobtain.c b/cpukit/rtems/src/semobtain.c
index 2faaff0..fe5710e 100644
--- a/cpukit/rtems/src/semobtain.c
+++ b/cpukit/rtems/src/semobtain.c
@@ -1,20 +1,11 @@
-/*
- *  Semaphore Manager
- *
- *  DESCRIPTION:
- *
- *  This package is the implementation of the Semaphore Manager.
- *  This manager utilizes standard Dijkstra counting semaphores to provide
- *  synchronization and mutual exclusion capabilities.
- *
- *  Directives provided are:
- *
- *     + create a semaphore
- *     + get an ID of a semaphore
- *     + delete a semaphore
- *     + acquire a semaphore
- *     + release a semaphore
+/**
+ *  @file
  *
+ *  @brief RTEMS Obtain Semaphore
+ *  @ingroup ClassicSem
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -47,21 +38,6 @@
 
 #include <rtems/score/interr.h>
 
-/*
- *  rtems_semaphore_obtain
- *
- *  This directive allows a thread to acquire a semaphore.
- *
- *  Input parameters:
- *    id         - semaphore id
- *    option_set - wait option
- *    timeout    - number of ticks to wait (0 means wait forever)
- *
- *  Output parameters:
- *    RTEMS_SUCCESSFUL - if successful
- *    error code        - if unsuccessful
- */
-
 rtems_status_code rtems_semaphore_obtain(
   rtems_id        id,
   rtems_option    option_set,
diff --git a/cpukit/rtems/src/taskmode.c b/cpukit/rtems/src/taskmode.c
index 9fab226..63fe29c 100644
--- a/cpukit/rtems/src/taskmode.c
+++ b/cpukit/rtems/src/taskmode.c
@@ -1,6 +1,11 @@
-/*
- *  RTEMS Task Manager - Change Task Mode
+/**
+ *  @file
  *
+ *  @brief RTEMS Task Mode
+ *  @ingroup ClassicTasks
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2010.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -28,22 +33,6 @@
 #include <rtems/score/apiext.h>
 #include <rtems/score/sysstate.h>
 
-/*
- *  rtems_task_mode
- *
- *  This directive enables and disables several modes of
- *  execution for the requesting thread.
- *
- *  Input parameters:
- *    mode_set          - new mode
- *    mask              - mask
- *    previous_mode_set - address of previous mode set
- *
- *  Output:
- *    *previous_mode_set - previous mode set
- *     always return RTEMS_SUCCESSFUL;
- */
-
 rtems_status_code rtems_task_mode(
   rtems_mode  mode_set,
   rtems_mode  mask,
diff --git a/cpukit/rtems/src/taskvariableadd.c b/cpukit/rtems/src/taskvariableadd.c
index 415fe69..9a0bc3d 100644
--- a/cpukit/rtems/src/taskvariableadd.c
+++ b/cpukit/rtems/src/taskvariableadd.c
@@ -1,7 +1,11 @@
-/*
- *  rtems_task_variable_add - Add a per-task variable
- *
+/**
+ *  @file
  *
+ *  @brief RTEMS Add Task Variable
+ *  @ingroup ClassicTasks
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -18,12 +22,6 @@
 #include <rtems/rtems/tasks.h>
 #include <rtems/score/wkspace.h>
 
-/*
- *  rtems_task_variable_add
- *
- *  This directive registers a task variable.
- */
-
 rtems_status_code rtems_task_variable_add(
   rtems_id tid,
   void **ptr,
diff --git a/cpukit/rtems/src/timerdelete.c b/cpukit/rtems/src/timerdelete.c
index e7a0d15..f259280 100644
--- a/cpukit/rtems/src/timerdelete.c
+++ b/cpukit/rtems/src/timerdelete.c
@@ -1,7 +1,11 @@
-/*
- *  Timer Manager - rtems_timer_delete directive
- *
+/**
+ *  @file
  *
+ *  @brief RTEMS Delete Timer
+ *  @ingroup ClassicTimer
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -23,19 +27,6 @@
 #include <rtems/score/tod.h>
 #include <rtems/score/watchdog.h>
 
-/*
- *  rtems_timer_delete
- *
- *  This directive allows a thread to delete a timer.
- *
- *  Input parameters:
- *    id - timer id
- *
- *  Output parameters:
- *    RTEMS_SUCCESSFUL - if successful
- *    error code       - if unsuccessful
- */
-
 rtems_status_code rtems_timer_delete(
   rtems_id id
 )
diff --git a/cpukit/rtems/src/timerfireafter.c b/cpukit/rtems/src/timerfireafter.c
index f823a7b..267c1cf 100644
--- a/cpukit/rtems/src/timerfireafter.c
+++ b/cpukit/rtems/src/timerfireafter.c
@@ -1,7 +1,11 @@
-/*
- *  Timer Manager - rtems_timer_fire_after directive
- *
+/**
+ *  @file
  *
+ *  @brief RTEMS Timer Fire After
+ *  @ingroup ClassicTimer
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2007.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -23,22 +27,6 @@
 #include <rtems/score/tod.h>
 #include <rtems/score/watchdog.h>
 
-/*
- *  rtems_timer_fire_after
- *
- *  This directive allows a thread to start a timer.
- *
- *  Input parameters:
- *    id        - timer id
- *    ticks     - interval until routine is fired
- *    routine   - routine to schedule
- *    user_data - passed as argument to routine when it is fired
- *
- *  Output parameters:
- *    RTEMS_SUCCESSFUL - if successful
- *    error code       - if unsuccessful
- */
-
 rtems_status_code rtems_timer_fire_after(
   rtems_id                           id,
   rtems_interval                     ticks,
diff --git a/cpukit/rtems/src/workspace.c b/cpukit/rtems/src/workspace.c
index 7af5897..38747be 100644
--- a/cpukit/rtems/src/workspace.c
+++ b/cpukit/rtems/src/workspace.c
@@ -1,6 +1,11 @@
-/*
- *  Workspace Handler
+/**
+ *  @file
  *
+ *  @brief RTEMS Workspace Support
+ *  @ingroup ClassicRTEMSWorkspace
+ */
+
+/*
  *  COPYRIGHT (c) 1989-2009.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -32,9 +37,6 @@ bool rtems_workspace_get_information(
   return _Protected_heap_Get_information( &_Workspace_Area, the_info );
 }
 
-/*
- *  _Workspace_Allocate
- */
 bool rtems_workspace_allocate(
   size_t      bytes,
   void      **pointer
@@ -62,9 +64,6 @@ bool rtems_workspace_allocate(
   return true;
 }
 
-/*
- *  _Workspace_Allocate
- */
 bool rtems_workspace_free(
   void *pointer
 )




More information about the vc mailing list