[rtems commit] Use a common phrase for pointer parameters
Sebastian Huber
sebh at rtems.org
Tue Jun 15 08:40:24 UTC 2021
Module: rtems
Branch: master
Commit: 6abdd89f191a5e6d64055093f68a4fce10554f82
Changeset: http://git.rtems.org/rtems/commit/?id=6abdd89f191a5e6d64055093f68a4fce10554f82
Author: Sebastian Huber <sebastian.huber at embedded-brains.de>
Date: Mon Jun 14 09:57:51 2021 +0200
Use a common phrase for pointer parameters
Mention the type of the pointer in the parameter description. Use the
more general term "object" instead of "variable".
Update #3993.
---
cpukit/include/rtems/io.h | 7 ++-
cpukit/include/rtems/rtems/barrier.h | 16 ++---
cpukit/include/rtems/rtems/clock.h | 30 ++++-----
cpukit/include/rtems/rtems/dpmem.h | 20 +++---
cpukit/include/rtems/rtems/intr.h | 4 +-
cpukit/include/rtems/rtems/message.h | 42 ++++++-------
cpukit/include/rtems/rtems/object.h | 10 +--
cpukit/include/rtems/rtems/part.h | 16 ++---
cpukit/include/rtems/rtems/ratemon.h | 24 ++++----
cpukit/include/rtems/rtems/region.h | 32 +++++-----
cpukit/include/rtems/rtems/sem.h | 18 +++---
cpukit/include/rtems/rtems/support.h | 10 +--
cpukit/include/rtems/rtems/tasks.h | 114 +++++++++++++++++------------------
cpukit/include/rtems/rtems/timer.h | 18 +++---
14 files changed, 180 insertions(+), 181 deletions(-)
diff --git a/cpukit/include/rtems/io.h b/cpukit/include/rtems/io.h
index d8ce527..181da9f 100644
--- a/cpukit/include/rtems/io.h
+++ b/cpukit/include/rtems/io.h
@@ -194,9 +194,10 @@ typedef struct {
*
* @param driver_table is the device driver address table.
*
- * @param[out] registered_major is the pointer to a device major number
- * variable. When the directive call is successful, the device major number
- * of the registered device will be stored in this variable.
+ * @param[out] registered_major is the pointer to an
+ * ::rtems_device_major_number object. When the directive call is
+ * successful, the device major number of the registered device will be
+ * stored in this object.
*
* @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
*
diff --git a/cpukit/include/rtems/rtems/barrier.h b/cpukit/include/rtems/rtems/barrier.h
index 0f692e1..6327a7c 100644
--- a/cpukit/include/rtems/rtems/barrier.h
+++ b/cpukit/include/rtems/rtems/barrier.h
@@ -88,9 +88,9 @@ extern "C" {
* @param maximum_waiters is the maximum count of waiters on an automatic
* release barrier.
*
- * @param id is the pointer to an object identifier variable. When the
- * directive call is successful, the identifier of the created barrier will
- * be stored in this variable.
+ * @param id is the pointer to an ::rtems_id object. When the directive call
+ * is successful, the identifier of the created barrier will be stored in
+ * this object.
*
* This directive creates a barrier which resides on the local node. The
* barrier has the user-defined object name specified in ``name`` and the
@@ -178,9 +178,9 @@ rtems_status_code rtems_barrier_create(
*
* @param name is the object name to look up.
*
- * @param[out] id is the pointer to an object identifier variable. When the
- * directive call is successful, the object identifier of an object with the
- * specified name will be stored in this variable.
+ * @param[out] id is the pointer to an ::rtems_id object. When the directive
+ * call is successful, the object identifier of an object with the specified
+ * name will be stored in this object.
*
* This directive obtains a barrier identifier associated with the barrier name
* specified in ``name``.
@@ -318,9 +318,9 @@ rtems_status_code rtems_barrier_wait( rtems_id id, rtems_interval timeout );
*
* @param id is the barrier identifier.
*
- * @param[out] released is the pointer to an integer variable. When the
+ * @param[out] released is the pointer to an uint32_t object. When the
* directive call is successful, the number of released tasks will be stored
- * in this variable.
+ * in this object.
*
* This directive releases the barrier specified by ``id``. All tasks waiting
* at the barrier will be unblocked. The number of released tasks will be
diff --git a/cpukit/include/rtems/rtems/clock.h b/cpukit/include/rtems/rtems/clock.h
index 3e94a1f..1eeb0ce 100644
--- a/cpukit/include/rtems/rtems/clock.h
+++ b/cpukit/include/rtems/rtems/clock.h
@@ -144,10 +144,10 @@ rtems_status_code rtems_clock_set( const rtems_time_of_day *time_of_day );
*
* @brief Gets the time of day associated with the current CLOCK_REALTIME.
*
- * @param time_of_day is the pointer to a RTEMS time of day variable. When the
+ * @param time_of_day is the pointer to an rtems_time_of_day object. When the
* directive call is successful, the time of day associated with the
* CLOCK_REALTIME at some point during the directive call will be stored in
- * this variable.
+ * this object.
*
* @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
*
@@ -177,10 +177,10 @@ rtems_status_code rtems_clock_get_tod( rtems_time_of_day *time_of_day );
* @brief Gets the seconds and microseconds elapsed since the Unix epoch and
* the current CLOCK_REALTIME.
*
- * @param[out] time_of_day is the pointer to a timeval structure variable.
- * When the directive call is successful, the seconds and microseconds
- * elapsed since the Unix epoch and the CLOCK_REALTIME at some point during
- * the directive call will be stored in this variable.
+ * @param[out] time_of_day is the pointer to a struct timeval object. When the
+ * directive call is successful, the seconds and microseconds elapsed since
+ * the Unix epoch and the CLOCK_REALTIME at some point during the directive
+ * call will be stored in this object.
*
* @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
*
@@ -210,10 +210,10 @@ rtems_status_code rtems_clock_get_tod_timeval( struct timeval *time_of_day );
* @brief Gets the seconds elapsed since the RTEMS epoch and the current
* CLOCK_REALTIME.
*
- * @param[out] seconds_since_rtems_epoch is the pointer to an interval
- * variable. When the directive call is successful, the seconds elapsed
- * since the RTEMS epoch and the CLOCK_REALTIME at some point during the
- * directive call will be stored in this variable.
+ * @param[out] seconds_since_rtems_epoch is the pointer to an ::rtems_interval
+ * object. When the directive call is successful, the seconds elapsed since
+ * the RTEMS epoch and the CLOCK_REALTIME at some point during the directive
+ * call will be stored in this object.
*
* @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
*
@@ -306,10 +306,10 @@ rtems_interval rtems_clock_get_ticks_since_boot( void );
* @brief Gets the seconds and nanoseconds elapsed since some time point during
* the system initialization using CLOCK_MONOTONIC.
*
- * @param[out] uptime is the pointer to a timeval structure variable. When the
+ * @param[out] uptime is the pointer to a struct timeval object. When the
* directive call is successful, the seconds and nanoseconds elapsed since
* some time point during the system initialization and some point during the
- * directive call using CLOCK_MONOTONIC will be stored in this variable.
+ * directive call using CLOCK_MONOTONIC will be stored in this object.
*
* @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
*
@@ -336,10 +336,10 @@ rtems_status_code rtems_clock_get_uptime( struct timespec *uptime );
* @brief Gets the seconds and microseconds elapsed since some time point
* during the system initialization using CLOCK_MONOTONIC.
*
- * @param[out] uptime is the pointer to a timeval structure variable. The
- * seconds and microseconds elapsed since some time point during the system
+ * @param[out] uptime is the pointer to a struct timeval object. The seconds
+ * and microseconds elapsed since some time point during the system
* initialization and some point during the directive call using
- * CLOCK_MONOTONIC will be stored in this variable. The pointer shall be
+ * CLOCK_MONOTONIC will be stored in this object. The pointer shall be
* valid, otherwise the behaviour is undefined.
*
* @par Constraints
diff --git a/cpukit/include/rtems/rtems/dpmem.h b/cpukit/include/rtems/rtems/dpmem.h
index 0dfa70a..9ecdf3a 100644
--- a/cpukit/include/rtems/rtems/dpmem.h
+++ b/cpukit/include/rtems/rtems/dpmem.h
@@ -89,9 +89,9 @@ extern "C" {
*
* @param length is the length in bytes of the memory area.
*
- * @param[out] id is the pointer to an object identifier variable. When the
- * directive call is successful, the identifier of the created port will be
- * stored in this variable.
+ * @param[out] id is the pointer to an ::rtems_id object. When the directive
+ * call is successful, the identifier of the created port will be stored in
+ * this object.
*
* This directive creates a port which resides on the local node. The port has
* the user-defined object name specified in ``name``. The assigned object
@@ -160,9 +160,9 @@ rtems_status_code rtems_port_create(
*
* @param name is the object name to look up.
*
- * @param[out] id is the pointer to an object identifier variable. When the
- * directive call is successful, the object identifier of an object with the
- * specified name will be stored in this variable.
+ * @param[out] id is the pointer to an ::rtems_id object. When the directive
+ * call is successful, the object identifier of an object with the specified
+ * name will be stored in this object.
*
* This directive obtains a port identifier associated with the port name
* specified in ``name``.
@@ -251,9 +251,9 @@ rtems_status_code rtems_port_delete( rtems_id id );
*
* @param external is the external address to convert.
*
- * @param[out] internal is the pointer to a pointer variable. When the
+ * @param[out] internal is the pointer to a ``void`` pointer object. When the
* directive call is successful, the external address associated with the
- * internal address will be stored in this variable.
+ * internal address will be stored in this object.
*
* This directive converts a dual-ported memory address from external to
* internal representation for the specified port. If the given external
@@ -297,9 +297,9 @@ rtems_status_code rtems_port_external_to_internal(
*
* @param internal is the internal address to convert.
*
- * @param[out] external is the pointer to a pointer variable. When the
+ * @param[out] external is the pointer to a ``void`` pointer object. When the
* directive call is successful, the external address associated with the
- * internal address will be stored in this variable.
+ * internal address will be stored in this object.
*
* This directive converts a dual-ported memory address from internal to
* external representation so that it can be passed to owner of the DPMA
diff --git a/cpukit/include/rtems/rtems/intr.h b/cpukit/include/rtems/rtems/intr.h
index c9222fc..178cf34 100644
--- a/cpukit/include/rtems/rtems/intr.h
+++ b/cpukit/include/rtems/rtems/intr.h
@@ -155,10 +155,10 @@ typedef ISR_Vector_number rtems_vector_number;
*
* @param vector is the interrupt vector number.
*
- * @param[out] old_isr_handler is the pointer to an ::rtems_isr_entry variable.
+ * @param[out] old_isr_handler is the pointer to an ::rtems_isr_entry object.
* When the directive call is successful, the previous interrupt service
* routine established for this interrupt vector will be stored in this
- * variable.
+ * object.
*
* This directive establishes an interrupt service routine (ISR) for the
* interrupt specified by the ``vector`` number. The ``new_isr_handler``
diff --git a/cpukit/include/rtems/rtems/message.h b/cpukit/include/rtems/rtems/message.h
index 747daf4..01173d4 100644
--- a/cpukit/include/rtems/rtems/message.h
+++ b/cpukit/include/rtems/rtems/message.h
@@ -151,9 +151,9 @@ typedef struct {
*
* @param attribute_set is the attribute set of the message queue.
*
- * @param[out] id is the pointer to an object identifier variable. When the
- * directive call is successful, the identifier of the created message queue
- * will be stored in this variable.
+ * @param[out] id is the pointer to an ::rtems_id object. When the directive
+ * call is successful, the identifier of the created message queue will be
+ * stored in this object.
*
* This directive creates a message queue which resides on the local node. The
* message queue has the user-defined object name specified in ``name``.
@@ -288,9 +288,9 @@ rtems_status_code rtems_message_queue_create(
*
* @param config is the message queue configuration.
*
- * @param[out] id is the pointer to an object identifier variable. When the
- * directive call is successful, the identifier of the constructed message
- * queue will be stored in this variable.
+ * @param[out] id is the pointer to an ::rtems_id object. When the directive
+ * call is successful, the identifier of the constructed message queue will
+ * be stored in this object.
*
* @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
*
@@ -388,9 +388,9 @@ rtems_status_code rtems_message_queue_construct(
*
* @param node is the node or node set to search for a matching object.
*
- * @param[out] id is the pointer to an object identifier variable. When the
- * directive call is successful, the object identifier of an object with the
- * specified name will be stored in this variable.
+ * @param[out] id is the pointer to an ::rtems_id object. When the directive
+ * call is successful, the object identifier of an object with the specified
+ * name will be stored in this object.
*
* This directive obtains a message queue identifier associated with the
* message queue name specified in ``name``.
@@ -647,9 +647,9 @@ rtems_status_code rtems_message_queue_urgent(
*
* @param size is the size in bytes of the message buffer to broadcast.
*
- * @param[out] count is the pointer to an uint32_t variable. When the
- * directive call is successful, the number of unblocked tasks will be stored
- * in this variable.
+ * @param[out] count is the pointer to an uint32_t object. When the directive
+ * call is successful, the number of unblocked tasks will be stored in this
+ * object.
*
* This directive causes all tasks that are waiting at the queue specified by
* ``id`` to be unblocked and sent the message contained in ``buffer``. Before
@@ -713,9 +713,9 @@ rtems_status_code rtems_message_queue_broadcast(
* rtems_message_queue_construct(). The ``size`` parameter cannot be used to
* specify the size of the buffer.
*
- * @param size is the pointer to a size_t variable. When the directive call is
- * successful, the size in bytes of the received messages will be stored in
- * this variable. This parameter cannot be used to specify the size of the
+ * @param[out] size is the pointer to a size_t object. When the directive call
+ * is successful, the size in bytes of the received messages will be stored
+ * in this object. This parameter cannot be used to specify the size of the
* buffer.
*
* @param option_set is the option set.
@@ -819,9 +819,9 @@ rtems_status_code rtems_message_queue_receive(
*
* @param id is the queue identifier.
*
- * @param[out] count is the pointer to an uint32_t variable. When the
- * directive call is successful, the number of pending messages will be
- * stored in this variable.
+ * @param[out] count is the pointer to an uint32_t object. When the directive
+ * call is successful, the number of pending messages will be stored in this
+ * object.
*
* This directive returns the number of messages pending on the queue specified
* by ``id`` in ``count``. If no messages are present on the queue, count is
@@ -861,9 +861,9 @@ rtems_status_code rtems_message_queue_get_number_pending(
*
* @param id is the queue identifier.
*
- * @param[out] count is the pointer to an uint32_t variable. When the
- * directive call is successful, the number of unblocked tasks will be stored
- * in this variable.
+ * @param[out] count is the pointer to an uint32_t object. When the directive
+ * call is successful, the number of unblocked tasks will be stored in this
+ * object.
*
* This directive removes all pending messages from the queue specified by
* ``id``. The number of messages removed is returned in ``count``. If no
diff --git a/cpukit/include/rtems/rtems/object.h b/cpukit/include/rtems/rtems/object.h
index 5f3e050..e80303d 100644
--- a/cpukit/include/rtems/rtems/object.h
+++ b/cpukit/include/rtems/rtems/object.h
@@ -304,9 +304,9 @@ rtems_name rtems_build_name( char c1, char c2, char c3, char c4 );
*
* @param id is the object identifier to get the name.
*
- * @param[out] name is the pointer to an object name variable. When the
+ * @param[out] name is the pointer to an ::rtems_name object. When the
* directive call is successful, the object name associated with the object
- * identifier will be stored in this variable.
+ * identifier will be stored in this object.
*
* @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
*
@@ -730,9 +730,9 @@ const char *rtems_object_get_api_class_name( int the_api, int the_class );
* @param the_class is the object class of the object API to get the class
* information.
*
- * @param info is the pointer to an object class information variable. When
- * the directive call is successful, the object class information of the
- * class of the API will be stored in this variable.
+ * @param[out] info is the pointer to an rtems_object_api_class_information
+ * object. When the directive call is successful, the object class
+ * information of the class of the API will be stored in this object.
*
* @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
*
diff --git a/cpukit/include/rtems/rtems/part.h b/cpukit/include/rtems/rtems/part.h
index 7a829d9..10091b4 100644
--- a/cpukit/include/rtems/rtems/part.h
+++ b/cpukit/include/rtems/rtems/part.h
@@ -112,9 +112,9 @@ extern "C" {
*
* @param attribute_set is the attribute set of the partition.
*
- * @param[out] id is the pointer to an object identifier variable. When the
- * directive call is successful, the identifier of the created partition will
- * be stored in this variable.
+ * @param[out] id is the pointer to an ::rtems_id object. When the directive
+ * call is successful, the identifier of the created partition will be stored
+ * in this object.
*
* This directive creates a partition of fixed size buffers from a physically
* contiguous memory space which starts at ``starting_address`` and is
@@ -252,9 +252,9 @@ rtems_status_code rtems_partition_create(
*
* @param node is the node or node set to search for a matching object.
*
- * @param[out] id is the pointer to an object identifier variable. When the
- * directive call is successful, the object identifier of an object with the
- * specified name will be stored in this variable.
+ * @param[out] id is the pointer to an ::rtems_id object. When the directive
+ * call is successful, the object identifier of an object with the specified
+ * name will be stored in this object.
*
* This directive obtains a partition identifier associated with the partition
* name specified in ``name``.
@@ -388,9 +388,9 @@ rtems_status_code rtems_partition_delete( rtems_id id );
*
* @param id is the partition identifier.
*
- * @param[out] buffer is the pointer to a buffer pointer variable. When the
+ * @param[out] buffer is the pointer to a ``void`` pointer object. When the
* directive call is successful, the pointer to the allocated buffer will be
- * stored in this variable.
+ * stored in this object.
*
* This directive allows a buffer to be obtained from the partition specified
* by ``id``. The address of the allocated buffer is returned through the
diff --git a/cpukit/include/rtems/rtems/ratemon.h b/cpukit/include/rtems/rtems/ratemon.h
index eee4a37..54c2709 100644
--- a/cpukit/include/rtems/rtems/ratemon.h
+++ b/cpukit/include/rtems/rtems/ratemon.h
@@ -228,9 +228,9 @@ struct rtems_printer;
*
* @param name is the object name of the period.
*
- * @param[out] id is the pointer to an object identifier variable. When the
- * directive call is successful, the identifier of the created period will be
- * stored in this variable.
+ * @param[out] id is the pointer to an ::rtems_id object. When the directive
+ * call is successful, the identifier of the created period will be stored in
+ * this object.
*
* This directive creates a period which resides on the local node. The period
* has the user-defined object name specified in ``name`` The assigned object
@@ -285,9 +285,9 @@ rtems_status_code rtems_rate_monotonic_create( rtems_name name, rtems_id *id );
*
* @param name is the object name to look up.
*
- * @param[out] id is the pointer to an object identifier variable. When the
- * directive call is successful, the object identifier of an object with the
- * specified name will be stored in this variable.
+ * @param[out] id is the pointer to an ::rtems_id object. When the directive
+ * call is successful, the object identifier of an object with the specified
+ * name will be stored in this object.
*
* This directive obtains a period identifier associated with the period name
* specified in ``name``.
@@ -467,9 +467,9 @@ rtems_status_code rtems_rate_monotonic_period(
*
* @param id is the rate monotonic period identifier.
*
- * @param[out] status is the pointer to a rtems_rate_monotonic_period_status
- * variable. When the directive call is successful, the detailed period
- * status will be stored in this variable.
+ * @param[out] status is the pointer to an rtems_rate_monotonic_period_status
+ * object. When the directive call is successful, the detailed period status
+ * will be stored in this object.
*
* This directive returns the detailed status of the rate monotonic period
* specified by ``id``. The detailed status of the period will be returned in
@@ -528,9 +528,9 @@ rtems_status_code rtems_rate_monotonic_get_status(
*
* @param id is the rate monotonic period identifier.
*
- * @param[out] status is the pointer to a
- * rtems_rate_monotonic_period_statistics variable. When the directive call
- * is successful, the period statistics will be stored in this variable.
+ * @param[out] status is the pointer to an
+ * rtems_rate_monotonic_period_statistics object. When the directive call is
+ * successful, the period statistics will be stored in this object.
*
* This directive returns the statistics of the rate monotonic period specified
* by ``id``. The statistics of the period will be returned in the members of
diff --git a/cpukit/include/rtems/rtems/region.h b/cpukit/include/rtems/rtems/region.h
index d4921ee..1e35344 100644
--- a/cpukit/include/rtems/rtems/region.h
+++ b/cpukit/include/rtems/rtems/region.h
@@ -87,9 +87,9 @@ extern "C" {
*
* @param segment is the begin address of the segment.
*
- * @param[out] size is the pointer to a uintptr_t variable. When the directive
+ * @param[out] size is the pointer to a uintptr_t object. When the directive
* call is successful, the size of the segment in bytes will be stored in
- * this variable.
+ * this object.
*
* This directive obtains the size in bytes of the segment specified by
* ``segment`` of the region specified by ``id`` in ``size``.
@@ -148,9 +148,9 @@ rtems_status_code rtems_region_get_segment_size(
*
* @param attribute_set is the attribute set of the region.
*
- * @param[out] id is the pointer to an object identifier variable. When the
- * directive call is successful, the identifier of the created region will be
- * stored in this variable.
+ * @param[out] id is the pointer to an ::rtems_id object. When the directive
+ * call is successful, the identifier of the created region will be stored in
+ * this object.
*
* This directive creates a region which resides on the local node. The region
* has the user-defined object name specified in ``name``. The assigned object
@@ -242,9 +242,9 @@ rtems_status_code rtems_region_create(
*
* @param name is the object name to look up.
*
- * @param[out] id is the pointer to an object identifier variable. When the
- * directive call is successful, the object identifier of an object with the
- * specified name will be stored in this variable.
+ * @param[out] id is the pointer to an ::rtems_id object. When the directive
+ * call is successful, the object identifier of an object with the specified
+ * name will be stored in this object.
*
* This directive obtains a region identifier associated with the region name
* specified in ``name``.
@@ -400,9 +400,9 @@ rtems_status_code rtems_region_extend(
* @param timeout is the timeout in clock ticks if the #RTEMS_WAIT option is
* set. Use #RTEMS_NO_TIMEOUT to wait potentially forever.
*
- * @param segment is the pointer to a void pointer variable. When the
+ * @param[out] segment is the pointer to a ``void`` pointer object. When the
* directive call is successful, the begin address of the allocated segment
- * will be stored in this variable.
+ * will be stored in this object.
*
* This directive gets a segment from the region specified by ``id``.
*
@@ -558,9 +558,9 @@ rtems_status_code rtems_region_return_segment( rtems_id id, void *segment );
*
* @param size is the requested new size of the segment.
*
- * @param[out] old_size is the pointer to an uintptr_t variable. When the
+ * @param[out] old_size is the pointer to an uintptr_t object. When the
* directive call is successful, the old size of the segment will be stored
- * in this variable.
+ * in this object.
*
* This directive is used to increase or decrease the size of the ``segment``
* of the region specified by ``id``. When increasing the size of a segment,
@@ -613,9 +613,9 @@ rtems_status_code rtems_region_resize_segment(
*
* @param id is the region identifier.
*
- * @param[out] the_info is the pointer to a Heap_Information_block variable.
+ * @param[out] the_info is the pointer to a Heap_Information_block object.
* When the directive call is successful, the information of the region will
- * be stored in this variable.
+ * be stored in this object.
*
* This directive is used to obtain information about the used and free memory
* in the region specified by ``id``. This is a snapshot at the time of the
@@ -668,9 +668,9 @@ rtems_status_code rtems_region_get_information(
*
* @param id is the region identifier.
*
- * @param[out] the_info is the pointer to a Heap_Information_block variable.
+ * @param[out] the_info is the pointer to a Heap_Information_block object.
* When the directive call is successful, the free information of the region
- * will be stored in this variable.
+ * will be stored in this object.
*
* This directive is used to obtain information about the free memory in the
* region specified by ``id``. This is a snapshot at the time of the call. The
diff --git a/cpukit/include/rtems/rtems/sem.h b/cpukit/include/rtems/rtems/sem.h
index d079926..2cf3ba2 100644
--- a/cpukit/include/rtems/rtems/sem.h
+++ b/cpukit/include/rtems/rtems/sem.h
@@ -95,9 +95,9 @@ extern "C" {
* semaphore with the priority ceiling or MrsP locking protocol as defined by
* the attribute set.
*
- * @param[out] id is the pointer to an object identifier variable. When the
- * directive call is successful, the identifier of the created semaphore will
- * be stored in this variable.
+ * @param[out] id is the pointer to an ::rtems_id object. When the directive
+ * call is successful, the identifier of the created semaphore will be stored
+ * in this object.
*
* This directive creates a semaphore which resides on the local node. The
* semaphore has the user-defined object name specified in ``name`` and the
@@ -272,9 +272,9 @@ rtems_status_code rtems_semaphore_create(
*
* @param node is the node or node set to search for a matching object.
*
- * @param[out] id is the pointer to an object identifier variable. When the
- * directive call is successful, the object identifier of an object with the
- * specified name will be stored in this variable.
+ * @param[out] id is the pointer to an ::rtems_id object. When the directive
+ * call is successful, the object identifier of an object with the specified
+ * name will be stored in this object.
*
* This directive obtains a semaphore identifier associated with the semaphore
* name specified in ``name``.
@@ -737,9 +737,9 @@ rtems_status_code rtems_semaphore_flush( rtems_id id );
* @param new_priority is the new priority corresponding to the specified
* scheduler.
*
- * @param[out] old_priority is the pointer to a task priority variable. When
- * the directive call is successful, the old priority of the semaphore
- * corresponding to the specified scheduler will be stored in this variable.
+ * @param[out] old_priority is the pointer to an ::rtems_task_priority object.
+ * When the directive call is successful, the old priority of the semaphore
+ * corresponding to the specified scheduler will be stored in this object.
*
* This directive sets the priority of the semaphore specified by
* ``semaphore_id``. The priority corresponds to the scheduler specified by
diff --git a/cpukit/include/rtems/rtems/support.h b/cpukit/include/rtems/rtems/support.h
index 829548a..60e090c 100644
--- a/cpukit/include/rtems/rtems/support.h
+++ b/cpukit/include/rtems/rtems/support.h
@@ -228,9 +228,9 @@ static inline void rtems_name_to_characters(
*
* @param bytes is the number of bytes to allocated.
*
- * @param[out] pointer is the pointer to a pointer variable. When the
+ * @param[out] pointer is the pointer to a ``void`` pointer object. When the
* directive call is successful, the begin address of the allocated memory
- * area will be stored in this variable.
+ * area will be stored in this object.
*
* @return Returns true, if the allocation was successful, otherwise false.
*
@@ -286,9 +286,9 @@ bool rtems_workspace_free( void *pointer );
*
* @brief Gets information about the RTEMS Workspace.
*
- * @param the_info is the pointer to a heap information variable. When the
- * directive call is successful, the heap information will be stored in this
- * variable.
+ * @param[out] the_info is the pointer to a Heap_Information_block object.
+ * When the directive call is successful, the heap information will be stored
+ * in this object.
*
* @return Returns true, if getting the information was successful, otherwise
* false.
diff --git a/cpukit/include/rtems/rtems/tasks.h b/cpukit/include/rtems/rtems/tasks.h
index 4b095a4..2a42dcd 100644
--- a/cpukit/include/rtems/rtems/tasks.h
+++ b/cpukit/include/rtems/rtems/tasks.h
@@ -449,9 +449,9 @@ rtems_task_priority _RTEMS_Maximum_priority( void );
*
* @param name is the scheduler name to look up.
*
- * @param[out] id is the pointer to an object identifier variable. When the
- * directive call is successful, the identifier of the scheduler will be
- * stored in this variable.
+ * @param[out] id is the pointer to an ::rtems_id object. When the directive
+ * call is successful, the identifier of the scheduler will be stored in this
+ * object.
*
* This directive obtains a scheduler identifier associated with the scheduler
* name specified in ``name``.
@@ -491,9 +491,9 @@ rtems_status_code rtems_scheduler_ident( rtems_name name, rtems_id *id );
*
* @param cpu_index is the processor index to identify the scheduler.
*
- * @param[out] id is the pointer to an object identifier variable. When the
- * directive call is successful, the identifier of the scheduler will be
- * stored in this variable.
+ * @param[out] id is the pointer to an ::rtems_id object. When the directive
+ * call is successful, the identifier of the scheduler will be stored in this
+ * object.
*
* @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
*
@@ -525,15 +525,15 @@ rtems_status_code rtems_scheduler_ident_by_processor(
*
* @brief Identifies a scheduler by the processor set.
*
- * @param cpusetsize is the size of the referenced processor set variable in
- * bytes. This value shall be positive.
+ * @param cpusetsize is the size of the processor set referenced by ``cpuset``
+ * in bytes. The size shall be positive.
*
- * @param cpuset is the pointer to a processor set variable. The referenced
- * processor set will be used to identify the scheduler.
+ * @param cpuset is the pointer to a cpu_set_t. The referenced processor set
+ * will be used to identify the scheduler.
*
- * @param[out] id is the pointer to an object identifier variable. When the
- * directive call is successful, the identifier of the scheduler will be
- * stored in this variable.
+ * @param[out] id is the pointer to an ::rtems_id object. When the directive
+ * call is successful, the identifier of the scheduler will be stored in this
+ * object.
*
* The scheduler is selected according to the highest numbered online processor
* in the specified processor set.
@@ -577,9 +577,9 @@ rtems_status_code rtems_scheduler_ident_by_processor_set(
*
* @param scheduler_id is the scheduler identifier.
*
- * @param[out] priority is the pointer to a task priority variable. The
- * maximum priority of the scheduler will be stored in this variable, if the
- * operation is successful.
+ * @param[out] priority is the pointer to an ::rtems_task_priority object.
+ * When the directive the maximum priority of the scheduler will be stored in
+ * this object.
*
* @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
*
@@ -614,10 +614,10 @@ rtems_status_code rtems_scheduler_get_maximum_priority(
*
* @param priority is the Classic API task priority to map.
*
- * @param[out] posix_priority is the pointer to a POSIX thread priority
- * variable. When the directive call is successful, the POSIX thread
- * priority value corresponding to the specified Classic API task priority
- * value will be stored in this variable.
+ * @param[out] posix_priority is the pointer to an ``int`` object. When the
+ * directive call is successful, the POSIX thread priority value
+ * corresponding to the specified Classic API task priority value will be
+ * stored in this object.
*
* @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
*
@@ -655,10 +655,10 @@ rtems_status_code rtems_scheduler_map_priority_to_posix(
*
* @param posix_priority is the POSIX thread priority to map.
*
- * @param[out] priority is the pointer to a Classic API task priority variable.
+ * @param[out] priority is the pointer to an ::rtems_task_priority object.
* When the directive call is successful, the Classic API task priority value
* corresponding to the specified POSIX thread priority value will be stored
- * in this variable.
+ * in this object.
*
* @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
*
@@ -764,14 +764,13 @@ uint32_t rtems_scheduler_get_processor_maximum( void );
*
* @param scheduler_id is the scheduler identifier.
*
- * @param cpusetsize is the size of the referenced processor set variable in
- * bytes.
+ * @param cpusetsize is the size of the processor set referenced by ``cpuset``
+ * in bytes.
*
- * @param[out] cpuset is the pointer to a processor set variable. When the
- * directive call is successful, the processor set of the scheduler will be
- * stored in this variable. A set bit in the processor set means that the
- * corresponding processor is owned by the scheduler, otherwise the bit is
- * cleared.
+ * @param[out] cpuset is the pointer to a cpu_set_t object. When the directive
+ * call is successful, the processor set of the scheduler will be stored in
+ * this object. A set bit in the processor set means that the corresponding
+ * processor is owned by the scheduler, otherwise the bit is cleared.
*
* @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
*
@@ -909,9 +908,9 @@ rtems_status_code rtems_scheduler_remove_processor(
*
* @param attribute_set is the attribute set of the task.
*
- * @param[out] id is the pointer to an object identifier variable. When the
- * directive call is successful, the identifier of the created task will be
- * stored in this variable.
+ * @param[out] id is the pointer to an ::rtems_id object. When the directive
+ * call is successful, the identifier of the created task will be stored in
+ * this object.
*
* This directive creates a task which resides on the local node. The task has
* the user-defined object name specified in ``name``. The assigned object
@@ -1145,9 +1144,9 @@ rtems_status_code rtems_task_create(
*
* @param config is the task configuration.
*
- * @param[out] id is the pointer to an object identifier variable. When the
- * directive call is successful, the identifier of the constructed task will
- * be stored in this variable.
+ * @param[out] id is the pointer to an ::rtems_id object. When the directive
+ * call is successful, the identifier of the constructed task will be stored
+ * in this object.
*
* @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
*
@@ -1259,9 +1258,9 @@ rtems_status_code rtems_task_construct(
*
* @param node is the node or node set to search for a matching object.
*
- * @param[out] id is the pointer to an object identifier variable. When the
- * directive call is successful, the object identifier of an object with the
- * specified name will be stored in this variable.
+ * @param[out] id is the pointer to an ::rtems_id object. When the directive
+ * call is successful, the object identifier of an object with the specified
+ * name will be stored in this object.
*
* This directive obtains a task identifier associated with the task name
* specified in ``name``.
@@ -1748,10 +1747,9 @@ rtems_status_code rtems_task_is_suspended( rtems_id id );
* @param new_priority is the new real priority or #RTEMS_CURRENT_PRIORITY to
* get the current priority.
*
- * @param[out] old_priority is the pointer to an ::rtems_task_priority
- * variable. When the directive call is successful, the current or previous
- * priority of the task with respect to its home scheduler will be stored in
- * this variable.
+ * @param[out] old_priority is the pointer to an ::rtems_task_priority object.
+ * When the directive call is successful, the current or previous priority of
+ * the task with respect to its home scheduler will be stored in this object.
*
* This directive manipulates the priority of the task specified by ``id``.
* When ``new_priority`` is not equal to #RTEMS_CURRENT_PRIORITY, the specified
@@ -1823,9 +1821,9 @@ rtems_status_code rtems_task_set_priority(
*
* @param scheduler_id is the scheduler identifier.
*
- * @param[out] priority is the pointer to an ::rtems_task_priority variable.
+ * @param[out] priority is the pointer to an ::rtems_task_priority object.
* When the directive call is successful, the current priority of the task
- * with respect to the specified scheduler will be stored in this variable.
+ * with respect to the specified scheduler will be stored in this object.
*
* This directive returns the current priority in ``priority`` of the task
* specified by ``task_id`` with respect to the scheduler specified by
@@ -1886,9 +1884,9 @@ rtems_status_code rtems_task_get_priority(
* applied to the calling task. When the value is #RTEMS_CURRENT_MODE, the
* mode of the calling task is not changed.
*
- * @param previous_mode_set is the pointer to a mode variable. When the
+ * @param previous_mode_set is the pointer to an ::rtems_mode object. When the
* directive call is successful, the mode of the task before any mode changes
- * done by the directive call will be stored in this variable.
+ * done by the directive call will be stored in this object.
*
* This directive queries and optionally manipulates the execution mode of the
* calling task. A task's execution mode enables and disables preemption,
@@ -2086,9 +2084,9 @@ rtems_status_code rtems_task_wake_when( const rtems_time_of_day *time_buffer );
* @param task_id is the task identifier. The constant #RTEMS_SELF may be used
* to specify the calling task.
*
- * @param[out] scheduler_id is the pointer to an ::rtems_id variable. When the
+ * @param[out] scheduler_id is the pointer to an ::rtems_id object. When the
* directive call is successful, the identifier of the home scheduler of the
- * task will be stored in this variable.
+ * task will be stored in this object.
*
* This directive returns the identifier of the home scheduler of the task
* specified by ``task_id`` in ``scheduler_id``.
@@ -2202,12 +2200,12 @@ rtems_status_code rtems_task_set_scheduler(
* @param id is the task identifier. The constant #RTEMS_SELF may be used to
* specify the calling task.
*
- * @param cpusetsize is the size of the referenced processor set variable in
- * bytes.
+ * @param cpusetsize is the size of the processor set referenced by ``cpuset``
+ * in bytes.
*
- * @param[out] cpuset is the pointer to a processor set variable. When the
- * directive call is successful, the processor affinity set of the task will
- * be stored in this variable. A set bit in the processor set means that the
+ * @param[out] cpuset is the pointer to a cpu_set_t object. When the directive
+ * call is successful, the processor affinity set of the task will be stored
+ * in this object. A set bit in the processor set means that the
* corresponding processor is in the processor affinity set of the task,
* otherwise the bit is cleared.
*
@@ -2221,8 +2219,8 @@ rtems_status_code rtems_task_set_scheduler(
* @retval ::RTEMS_INVALID_ID There was no task associated with the identifier
* specified by ``id``.
*
- * @retval ::RTEMS_INVALID_SIZE The provided processor set was too small for
- * the processor affinity set of the task.
+ * @retval ::RTEMS_INVALID_SIZE The size specified by ``cpusetsize`` of the
+ * processor set was too small for the processor affinity set of the task.
*
* @retval ::RTEMS_ILLEGAL_ON_REMOTE_OBJECT The task resided on a remote node.
*
@@ -2256,10 +2254,10 @@ rtems_status_code rtems_task_get_affinity(
* @param id is the task identifier. The constant #RTEMS_SELF may be used to
* specify the calling task.
*
- * @param cpusetsize is the size of the referenced processor set variable in
- * bytes.
+ * @param cpusetsize is the size of the processor set referenced by ``cpuset``
+ * in bytes.
*
- * @param cpuset is the pointer to a processor set variable. The processor set
+ * @param[out] cpuset is the pointer to a cpu_set_t object. The processor set
* defines the new processor affinity set of the task. A set bit in the
* processor set means that the corresponding processor shall be in the
* processor affinity set of the task, otherwise the bit shall be cleared.
diff --git a/cpukit/include/rtems/rtems/timer.h b/cpukit/include/rtems/rtems/timer.h
index eb8bef2..0f13c04 100644
--- a/cpukit/include/rtems/rtems/timer.h
+++ b/cpukit/include/rtems/rtems/timer.h
@@ -191,9 +191,9 @@ typedef struct {
*
* @param id is the timer identifier.
*
- * @param[out] the_info is the pointer to a timer information variable. When
- * the directive call is successful, the information about the timer will be
- * stored in this variable.
+ * @param[out] the_info is the pointer to an rtems_timer_information object.
+ * When the directive call is successful, the information about the timer
+ * will be stored in this object.
*
* This directive returns information about the timer.
*
@@ -267,9 +267,9 @@ typedef rtems_timer_service_routine ( *rtems_timer_service_routine_entry )( rtem
*
* @param name is the object name of the timer.
*
- * @param[out] id is the pointer to an object identifier variable. When the
- * directive call is successful, the identifier of the created timer will be
- * stored in this variable.
+ * @param[out] id is the pointer to an ::rtems_id object. When the directive
+ * call is successful, the identifier of the created timer will be stored in
+ * this object.
*
* This directive creates a timer which resides on the local node. The timer
* has the user-defined object name specified in ``name``. The assigned object
@@ -326,9 +326,9 @@ rtems_status_code rtems_timer_create( rtems_name name, rtems_id *id );
*
* @param name is the object name to look up.
*
- * @param[out] id is the pointer to an object identifier variable. When the
- * directive call is successful, the object identifier of an object with the
- * specified name will be stored in this variable.
+ * @param[out] id is the pointer to an ::rtems_id object. When the directive
+ * call is successful, the object identifier of an object with the specified
+ * name will be stored in this object.
*
* This directive obtains a timer identifier associated with the timer name
* specified in ``name``.
More information about the vc
mailing list