docs(api-queue): Update documentation for the Queue API

Author: Steve Cartmell

rtos/Queue.h

@@ -22,14 +22,11 @@
 #ifndef QUEUE_H
 #define QUEUE_H
 
-#include <stdint.h>
-#include <string.h>
-
 #include "cmsis_os2.h"
+#include "mbed_rtos1_types.h"
 #include "mbed_rtos_storage.h"
 #include "platform/mbed_error.h"
 #include "platform/NonCopyable.h"
-#include "mbed_rtos1_types.h"
 
 namespace rtos {
 /** \addtogroup rtos */
@@ -38,21 +35,31 @@ namespace rtos {
  * \defgroup rtos_Queue Queue class
  * @{
  */
- 
-/** The Queue class allow to control, send, receive, or wait for messages.
- A message can be a integer or pointer value  to a certain type T that is send
- to a thread or interrupt service routine.
-  @tparam  T         data type of a single message element.
-  @tparam  queue_sz  maximum number of messages in queue.
 
- @note
- Memory considerations: The queue control structures will be created on current thread's stack, both for the mbed OS
- and underlying RTOS objects (static or dynamic RTOS memory pools are not being used).
-*/
+/** The Queue class represents a collection of objects that are stored first by
+ *  order of priorty, and then in first-in, first-out (FIFO) order.
+ *
+ * A queue is used to when data needs to stored and then accessed in the same
+ * order that it has been stored. The order in which they are retrieved is in
+ * order of descending priority, if multiple elements have the same priority
+ * they are retrieved in FIFO order.
+ *
+ * The object type stored in the queue can be an integer, pointer, or a generic
+ * type given by the template parameter T.
+ *
+ * @tparam T        Specifies the type of elements that are stored in the queue.
+ * @tparam queue_sz Maximum number of messages that can be stored in the queue.
+ *
+ * @note Memory considerations: The queue control structures will be created on
+ *       current thread's stack, both for the mbed OS and underlying RTOS
+ *       objects (static or dynamic RTOS memory pools are not being used).
+ *
+ */
 template<typename T, uint32_t queue_sz>
 class Queue : private mbed::NonCopyable<Queue<T, queue_sz> > {
 public:
-    /** Create and initialize a message Queue.
+    /** Create and initialize a message Queue of objects of the parameterized
+     * type `T` and maximum capacity specified by `queue_sz`
      *
      * @note You cannot call this function from ISR context.
     */
@@ -66,6 +73,7 @@ class Queue : private mbed::NonCopyable<Queue<T, queue_sz> > {
         _id = osMessageQueueNew(queue_sz, sizeof(T*), &attr);
         MBED_ASSERT(_id);
     }
+
     /** Queue destructor
      *
      * @note You cannot call this function from ISR context.
@@ -94,33 +102,82 @@ class Queue : private mbed::NonCopyable<Queue<T, queue_sz> > {
         return osMessageQueueGetSpace(_id) == 0;
     }
 
-    /** Put a message in a Queue.
-      @param   data      message pointer.
-      @param   millisec  timeout value or 0 in case of no time-out. (default: 0)
-      @param   prio      priority value or 0 in case of default. (default: 0)
-      @return  status code that indicates the execution status of the function:
-               @a osOK the message has been put into the queue.
-               @a osErrorTimeout the message could not be put into the queue in the given time.
-               @a osErrorResource not enough space in the queue.
-               @a osErrorParameter internal error or non-zero timeout specified in an ISR.
-
-      @note You may call this function from ISR context if the millisec parameter is set to 0.
-    */
+    /** Inserts the given element to the end of the queue.
+     *
+     * This function puts the message pointed to by `data` into the queue. The
+     * parameter `prio` is used to sort the message according to their priority
+     * (higher numbers indicate higher priority) on insertion.
+     *
+     * The timeout indicated by the parameter `millisec` specifies how long the
+     * function will block waiting for the message to be inserted into the
+     * queue.
+     *
+     * The parameter `millisec` can have the following values:
+     *  - When the timeout is 0 (the default), the function returns instantly.
+     *  - When the timeout is osWaitForever the function will wait for an
+     *    infinite time.
+     *  - For all other values the function will wait for the given number of
+     *    milliseconds.
+     *
+     * @param  data      Pointer to the element to insert into the queue.
+     * @param  millisec  Timeout for the operation to be executed, or 0 in case
+     *                   of no-timeout. (default: 0)
+     * @param  prio      Priority of the operation or 0 in case of default.
+     *                   (default: 0)
+     *
+     * @return Status code that indicates the execution status of the function:
+     *         @a osOK              The message has been successfully inserted
+     *                              into the queue.
+     *         @a osErrorTimeout    The message could not be inserted into the
+     *                              queue in the given time.
+     *         @a osErrorResource   The message could not be inserted because
+     *                              the queue is full.
+     *         @a osErrorParameter  Internal error or non-zero timeout specified
+     *                              in an ISR.
+     *
+     * @note You may call this function from ISR context if the millisec
+     *       parameter is set to 0.
+     *
+     */
     osStatus put(T* data, uint32_t millisec=0, uint8_t prio=0) {
         return osMessageQueuePut(_id, &data, prio, millisec);
     }
 
-    /** Get a message or Wait for a message from a Queue. Messages are retrieved in a descending priority order or
-        first in first out when the priorities are the same.
-      @param   millisec  timeout value or 0 in case of no time-out. (default: osWaitForever).
-      @return  event information that includes the message in event.value and the status code in event.status:
-               @a osEventMessage message received.
-               @a osOK no message is available in the queue and no timeout was specified.
-               @a osEventTimeout no message has arrived during the given timeout period.
-               @a osErrorParameter a parameter is invalid or outside of a permitted range.
-
-      @note You may call this function from ISR context if the millisec parameter is set to 0.
-    */
+    /** Get a message or wait for a message from the queue.
+     *
+     * This function retrieves a message from the queue. The message is stored
+     * in the value field of the returned `osEvent` object.
+     *
+     * The timeout specified by the parameter `millisec` specifies how long the
+     * function will wait to retrieve the message from the queue.
+     *
+     * The timeout parameter can have the following values:
+     *  - When the timeout is 0, the function returns instantly.
+     *  - When the timeout is osWaitForever (default), the function will wait
+     *    infinite time until the message is retrieved.
+     *  - When the timeout is any other value the function will wait for th
+     *    specified time before returning a timeout error.
+     *
+     * Messages are retrieved in descending priority order. If two messages
+     * share the same priority level they are retrieved in first-in, first-out
+     * (FIFO) order.
+     *
+     * @param   millisec  Timeout value or 0 in case of no time-out.
+     *                    (default: osWaitForever).
+     *
+     * @return Event information that includes the message in event. Message
+     *         value and the status code in event.status:
+     *         @a osEventMessage   Message successfully received.
+     *         @a osOK             No message is available in the queue and no
+     *                             timeout was specified.
+     *         @a osEventTimeout   No message was received before a timeout
+     *                             event occurred.
+     *         @a osErrorParameter A parameter is invalid or outside of a
+     *                             permitted range.
+     *
+     * @note  You may call this function from ISR context if the millisec
+     *        parameter is set to 0.
+     */
     osEvent get(uint32_t millisec=osWaitForever) {
         osEvent event;
         T *data = NULL;
@@ -155,6 +212,6 @@ class Queue : private mbed::NonCopyable<Queue<T, queue_sz> > {
 /** @}*/
 /** @}*/
 
-}
-#endif
+} // namespace rtos
 
+#endif // QUEUE_H