From 553b0ad5d395fb06e205907edd875b0abca235d0 Mon Sep 17 00:00:00 2001
From: Soren Ptak <ptaksoren@gmail.com>
Date: Fri, 15 Dec 2023 12:34:52 -0500
Subject: Update comments related to portYIELD_FROM_ISR() in queue.h #925

---
 include/queue.h | 23 ++++++++++++++++-------
 tasks.c         |  2 +-
 2 files changed, 17 insertions(+), 8 deletions(-)

diff --git a/include/queue.h b/include/queue.h
index b00a07f37..c6497b5b6 100644
--- a/include/queue.h
+++ b/include/queue.h
@@ -1185,9 +1185,12 @@ void vQueueDelete( QueueHandle_t xQueue ) PRIVILEGED_FUNCTION;
  *  {
  *      // Writing to the queue caused a task to unblock and the unblocked task
  *      // has a priority higher than or equal to the priority of the currently
- *      // executing task (the task this interrupt interrupted).  Perform a context
+ *      // executing task (the task this interrupt interrupted). Perform a context
  *      // switch so this interrupt returns directly to the unblocked task.
- *      portYIELD_FROM_ISR(); // or portEND_SWITCHING_ISR() depending on the port.
+ *      // The macro used is port specific and will be either
+ *      // portYIELD_FROM_ISR() or portEND_SWITCHING_ISR() - refer to the documentation
+ *      // page for the port being used.
+ *      portYIELD_FROM_ISR( xHigherPriorityTaskWoken );
  *  }
  * }
  * @endcode
@@ -1260,8 +1263,11 @@ void vQueueDelete( QueueHandle_t xQueue ) PRIVILEGED_FUNCTION;
  *  // Now the buffer is empty we can switch context if necessary.
  *  if( xHigherPriorityTaskWoken )
  *  {
- *      // Actual macro used here is port specific.
- *      portYIELD_FROM_ISR ();
+ *       // As xHigherPriorityTaskWoken is now set to pdTRUE then a context
+ *       // switch should be requested. The macro used is port specific and
+ *       // will be either portYIELD_FROM_ISR() or portEND_SWITCHING_ISR() -
+ *       // refer to the documentation page for the port being used.
+ *       portYIELD_FROM_ISR( xHigherPriorityTaskWoken );
  *  }
  * }
  * @endcode
@@ -1337,11 +1343,14 @@ void vQueueDelete( QueueHandle_t xQueue ) PRIVILEGED_FUNCTION;
  *
  *  } while( portINPUT_BYTE( BUFFER_COUNT ) );
  *
- *  // Now the buffer is empty we can switch context if necessary.  Note that the
- *  // name of the yield function required is port specific.
+ *  // Now the buffer is empty we can switch context if necessary.
  *  if( xHigherPriorityTaskWokenByPost )
  *  {
- *      portYIELD_FROM_ISR();
+ *       // As xHigherPriorityTaskWokenByPost is now set to pdTRUE then a context
+ *       // switch should be requested. The macro used is port specific and
+ *       // will be either portYIELD_FROM_ISR() or portEND_SWITCHING_ISR() -
+ *       // refer to the documentation page for the port being used.
+ *       portYIELD_FROM_ISR( xHigherPriorityTaskWokenByPost );
  *  }
  * }
  * @endcode
diff --git a/tasks.c b/tasks.c
index ccafc1e25..279d4bdb3 100644
--- a/tasks.c
+++ b/tasks.c
@@ -3463,7 +3463,7 @@ static void prvInitialiseNewTask( TaskFunction_t pxTaskCode,
 
                             /* Mark that a yield is pending in case the user is not
                              * using the return value to initiate a context switch
-                             * from the ISR using portYIELD_FROM_ISR. */
+                             * from the ISR using the port specific portYIELD_FROM_ISR(). */
                             xYieldPendings[ 0 ] = pdTRUE;
                         }
                         else
-- 
cgit v1.2.3