Update documentation for the Queue API

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 */
@@ -39,20 +36,30 @@ namespace rtos {
  * @{
  */
 
-/** 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.
+ *
+ * You can use a queue when you need to store data and then access it in the same
+ * order that it has been stored. The order in which you retrieve the data 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 stored in the queue.
+ * @tparam queue_sz Maximum number of messages that you can store in the queue.
+ *
+ * @note Memory considerations: The queue control structures are created on the
+ * 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.
  */
@@ -67,6 +74,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.
@@ -76,7 +84,7 @@ class Queue : private mbed::NonCopyable<Queue<T, queue_sz> > {
  osMessageQueueDelete(_id);
  }
 
- /** Check if the queue is empty
+ /** Check if the queue is empty.
  *
  * @return True if the queue is empty, false if not
  *
@@ -87,7 +95,7 @@ class Queue : private mbed::NonCopyable<Queue<T, queue_sz> > {
  return osMessageQueueGetCount(_id) == 0;
  }
 
- /** Check if the queue is full
+ /** Check if the queue is full.
  *
  * @return True if the queue is full, false if not
  *
@@ -98,36 +106,83 @@ 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.
- */
- osStatus put(T *data, uint32_t millisec = 0, uint8_t prio = 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 blocks 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 waits for an
+ * infinite time.
+ * - For all other values, the function waits 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 nonzero 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.
- */
- osEvent get(uint32_t millisec = osWaitForever)
- {
+ /** 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 waits 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 waits
+ * infinite time until the message is retrieved.
+ * - When the timeout is any other value, the function waits for the
+ * 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;
  osStatus_t res = osMessageQueueGet(_id, &data, NULL, millisec);
@@ -161,6 +216,6 @@ class Queue : private mbed::NonCopyable<Queue<T, queue_sz> > {
 /** @}*/
 /** @}*/
 
-}
-#endif
+} // namespace rtos
 
+#endif // QUEUE_H