1 files changed, 16 insertions, 11 deletions
diff --git a/cpukit/include/rtems/rtems/tasks.h b/cpukit/include/rtems/rtems/tasks.h
index 45be8a8730..84dd646fe7 100644
--- a/cpukit/include/rtems/rtems/tasks.h
+++ b/cpukit/include/rtems/rtems/tasks.h
@@ -10,7 +10,7 @@
 
 /*
  * Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG
- * Copyright (C) 1988, 2017 On-Line Applications Research Corporation (OAR)
+ * Copyright (C) 1988, 2023 On-Line Applications Research Corporation (OAR)
  *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions
@@ -234,7 +234,7 @@ typedef void rtems_task;
 /**
  * @ingroup RTEMSAPIClassicTasks
  *
- * @brief This type defines the entry point of an RTEMS task.
+ * @brief This type defines the task entry point of an RTEMS task.
  */
 typedef rtems_task ( *rtems_task_entry )( rtems_task_argument );
 
@@ -897,8 +897,8 @@ rtems_id rtems_task_self( void );
  *
  * This directive readies the task, specified by ``id``, for execution based on
  * the priority and execution mode specified when the task was created.  The
- * entry point of the task is given in ``entry_point``. The task's entry point
- * argument is contained in ``argument``.
+ * task entry point of the task is given in ``entry_point``.  The task's entry
+ * point argument is contained in ``argument``.
  *
  * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
  *
@@ -1544,15 +1544,16 @@ rtems_status_code rtems_task_mode(
 /**
  * @ingroup RTEMSAPIClassicTasks
  *
- * @brief Wakes up after an interval in clock ticks or yields the processor.
+ * @brief Wakes up after a count of clock ticks have occurred or yields the
+ *   processor.
  *
- * @param ticks is the interval in clock ticks to delay the task or
+ * @param ticks is the count of clock ticks to delay the task or
  *   #RTEMS_YIELD_PROCESSOR to yield the processor.
  *
- * This directive blocks the calling task for the specified ``ticks`` of clock
- * ticks if the value is not equal to #RTEMS_YIELD_PROCESSOR.  When the
- * requested interval has elapsed, the task is made ready.  The clock tick
- * directives automatically updates the delay period.  The calling task may
+ * This directive blocks the calling task for the specified ``ticks`` count of
+ * clock ticks if the value is not equal to #RTEMS_YIELD_PROCESSOR. When the
+ * requested count of ticks have occurred, the task is made ready.  The clock
+ * tick directives automatically update the delay period.  The calling task may
  * give up the processor and remain in the ready state by specifying a value of
  * #RTEMS_YIELD_PROCESSOR in ``ticks``.
  *
@@ -1561,7 +1562,11 @@ rtems_status_code rtems_task_mode(
  * @par Notes
  * Setting the system date and time with the rtems_clock_set() directive and
  * similar directives which set CLOCK_REALTIME have no effect on a
- * rtems_task_wake_after() blocked task.
+ * rtems_task_wake_after() blocked task.  The delay until first clock tick will
+ * never be a whole clock tick interval since this directive will never execute
+ * exactly on a clock tick.  Applications requiring use of a clock
+ * (CLOCK_REALTIME or CLOCK_MONOTONIC) instead of clock ticks should make use
+ * of clock_nanosleep().
  *
  * @par Constraints
  * @parblock