Update the documentation contained in the header files to be correct for V9.0.0 relea...

[freertos] / FreeRTOS / Source / include / queue.h

diff --git a/FreeRTOS/Source/include/queue.h b/FreeRTOS/Source/include/queue.h
index e8f54a435018a28c844ceb5c11261190f15d8996..a3e55221f83d8cd260527a3272e03e83e58e302a 100644 (file)
--- a/FreeRTOS/Source/include/queue.h
+++ b/FreeRTOS/Source/include/queue.h
@@ -126,16 +126,17 @@ typedef void * QueueSetMemberHandle_t;
  * Creates a new queue instance, and returns a handle by which the new queue\r
  * can be referenced.\r
  *\r
- * Internally, within the FreeRTOS implementation, queue's use two blocks of\r
+ * Internally, within the FreeRTOS implementation, queues use two blocks of\r
  * memory.  The first block is used to hold the queue's data structures.  The\r
  * second block is used to hold items placed into the queue.  If a queue is\r
  * created using xQueueCreate() then both blocks of memory are automatically\r
  * dynamically allocated inside the xQueueCreate() function.  (see\r
  * http://www.freertos.org/a00111.html).  If a queue is created using\r
- * xQueueCreateStatic() then the application writer can instead optionally\r
- * provide the memory that will get used by the queue.  xQueueCreateStatic()\r
- * therefore allows a queue to be created without using any dynamic memory\r
- * allocation.\r
+ * xQueueCreateStatic() then the application writer must provide the memory that\r
+ * will get used by the queue.  xQueueCreateStatic() therefore allows a queue to\r
+ * be created without using any dynamic memory allocation.\r
+ *\r
+ * http://www.FreeRTOS.org/Embedded-RTOS-Queues.html\r
  *\r
  * @param uxQueueLength The maximum number of items that the queue can contain.\r
  *\r
@@ -199,16 +200,17 @@ typedef void * QueueSetMemberHandle_t;
  * Creates a new queue instance, and returns a handle by which the new queue\r
  * can be referenced.\r
  *\r
- * Internally, within the FreeRTOS implementation, queue's use two blocks of\r
+ * Internally, within the FreeRTOS implementation, queues use two blocks of\r
  * memory.  The first block is used to hold the queue's data structures.  The\r
  * second block is used to hold items placed into the queue.  If a queue is\r
  * created using xQueueCreate() then both blocks of memory are automatically\r
  * dynamically allocated inside the xQueueCreate() function.  (see\r
  * http://www.freertos.org/a00111.html).  If a queue is created using\r
- * xQueueCreateStatic() then the application writer can instead optionally\r
- * provide the memory that will get used by the queue.  xQueueCreateStatic()\r
- * therefore allows a queue to be created without using any dynamic memory\r
- * allocation.\r
+ * xQueueCreateStatic() then the application writer must provide the memory that\r
+ * will get used by the queue.  xQueueCreateStatic() therefore allows a queue to\r
+ * be created without using any dynamic memory allocation.\r
+ *\r
+ * http://www.FreeRTOS.org/Embedded-RTOS-Queues.html\r
  *\r
  * @param uxQueueLength The maximum number of items that the queue can contain.\r
  *\r
@@ -217,27 +219,17 @@ typedef void * QueueSetMemberHandle_t;
  * that will be copied for each posted item.  Each item on the queue must be\r
  * the same size.\r
  *\r
- * @param pucQueueStorageBuffer If pucQueueStorageBuffer is NULL then the memory\r
- * used to hold items stored in the queue will be allocated dynamically, just as\r
- * when a queue is created using xQueueCreate().  If pxQueueStorageBuffer is not\r
- * NULL then it must point to a uint8_t array that is at least large enough to\r
- * hold the maximum number of items that can be in the queue at any one time -\r
- * which is ( uxQueueLength * uxItemsSize ) bytes.\r
- *\r
- * @param pxQueueBuffer If pxQueueBuffer is NULL then the memory required to\r
- * hold the queue's data structures will be allocated dynamically, just as when\r
- * a queue is created using xQueueCreate().  If pxQueueBuffer is not NULL then\r
- * it must point to a variable of type StaticQueue_t, which will then be used to\r
- * hold the queue's data structure, removing the need for the memory to be\r
- * allocated dynamically.\r
- *\r
- * @return If neither pucQueueStorageBuffer or pxQueueBuffer are NULL, then the\r
- * function will not attempt any dynamic memory allocation, and a handle to the\r
- * created queue will always be returned.  If pucQueueStorageBuffer or\r
- * pxQueueBuffer is NULL then the function will attempt to dynamically allocate\r
- * one of both buffers.  In this case, if the allocation succeeds then a handle\r
- * to the created queue will be returned, and if one of the the allocation fails\r
- * NULL will be returned.\r
+ * @param pucQueueStorageBuffer If uxItemSize is not zero then\r
+ * pucQueueStorageBuffer must point to a uint8_t array that is at least large\r
+ * enough to hold the maximum number of items that can be in the queue at any\r
+ * one time - which is ( uxQueueLength * uxItemsSize ) bytes.  If uxItemSize is\r
+ * zero then pucQueueStorageBuffer can be NULL.\r
+ *\r
+ * @param pxQueueBuffer Must point to a variable of type StaticQueue_t, which\r
+ * will be used to hold the queue's data structure.\r
+ *\r
+ * @return If the queue is created then a handle to the created queue is\r
+ * returned.  If pxQueueBuffer is NULL then NULL is returned.\r
  *\r
  * Example usage:\r
    <pre>\r
@@ -268,7 +260,7 @@ typedef void * QueueSetMemberHandle_t;
                                                        &xQueueBuffer ); // The buffer that will hold the queue structure.\r
 \r
        // The queue is guaranteed to be created successfully as no dynamic memory\r
-       // allocation was used.  Therefore xQueue1 is now a handle to a valid queue.\r
+       // allocation is used.  Therefore xQueue1 is now a handle to a valid queue.\r
 \r
        // ... Rest of task code.\r
  }\r