From 6abdd89f191a5e6d64055093f68a4fce10554f82 Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Mon, 14 Jun 2021 09:57:51 +0200 Subject: 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(-) (limited to 'cpukit/include') diff --git a/cpukit/include/rtems/io.h b/cpukit/include/rtems/io.h index d8ce527b0e..181da9fe4f 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 0f692e1995..6327a7c831 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 3e94a1f609..1eeb0ce54c 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 0dfa70a82e..9ecdf3a170 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 c9222fcc4d..178cf342df 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 747daf4e1b..01173d4029 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 5f3e050b3c..e80303da28 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 7a829d96af..10091b48f4 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 eee4a37319..54c2709ab8 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 d4921eec88..1e35344f7d 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 d079926720..2cf3ba232b 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 829548aae2..60e090ccec 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 4b095a4530..2a42dcd39c 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 eb8bef2532..0f13c04bda 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``. -- cgit v1.2.3