diff mbox

[11/16] api: odp_queue.h: updated return descriptions

Message ID 1422528008-29845-12-git-send-email-ola.liljedahl@linaro.org
State New
Headers show

Commit Message

Ola Liljedahl Jan. 29, 2015, 10:40 a.m. UTC 
Updated doxygen descriptions, particularly the @return/@retval descriptions.
No change of implementation necessary.

Signed-off-by: Ola Liljedahl <ola.liljedahl@linaro.org>
---
(This document/code contribution attached is provided under the terms of
agreement LES-LTM-21309)

 platform/linux-generic/include/api/odp_queue.h | 29 ++++++++++++++++----------
 1 file changed, 18 insertions(+), 11 deletions(-)
diff mbox

Patch

diff --git a/platform/linux-generic/include/api/odp_queue.h b/platform/linux-generic/include/api/odp_queue.h
index fceed4d..79c7e80 100644
--- a/platform/linux-generic/include/api/odp_queue.h
+++ b/platform/linux-generic/include/api/odp_queue.h
@@ -118,7 +118,8 @@  typedef struct odp_queue_param_t {
  * @param type    Queue type
  * @param param   Queue parameters. Uses defaults if NULL.
  *
- * @return Queue handle or ODP_QUEUE_INVALID
+ * @return Queue handle
+ * @retval ODP_QUEUE_INVALID on failure
  */
 odp_queue_t odp_queue_create(const char *name, odp_queue_type_t type,
 			     odp_queue_param_t *param);
@@ -133,7 +134,8 @@  odp_queue_t odp_queue_create(const char *name, odp_queue_type_t type,
  *
  * @param queue    Queue handle
  *
- * @return 0 if successful
+ * @retval 0 on success
+ * @retval <0 on failure
  */
 int odp_queue_destroy(odp_queue_t queue);
 
@@ -142,7 +144,8 @@  int odp_queue_destroy(odp_queue_t queue);
  *
  * @param name    Queue name
  *
- * @return Queue handle or ODP_QUEUE_INVALID
+ * @return Queue handle
+ * @retval ODP_QUEUE_INVALID on failure
  */
 odp_queue_t odp_queue_lookup(const char *name);
 
@@ -156,7 +159,8 @@  odp_queue_t odp_queue_lookup(const char *name);
  * @param queue    Queue handle
  * @param context  Address to the queue context
  *
- * @return 0 if successful
+ * @retval 0 on success
+ * @retval <0 on failure
  */
 int odp_queue_set_context(odp_queue_t queue, void *context);
 
@@ -165,8 +169,8 @@  int odp_queue_set_context(odp_queue_t queue, void *context);
  *
  * @param queue    Queue handle
  *
- * @return If successful, a pointer to the queue context,
- *         NULL for failure.
+ * @return pointer to the queue context
+ * @retval NULL on failure
  */
 void *odp_queue_get_context(odp_queue_t queue);
 
@@ -176,7 +180,8 @@  void *odp_queue_get_context(odp_queue_t queue);
  * @param queue   Queue handle
  * @param ev      Event handle
  *
- * @return 0 if succesful
+ * @retval 0 on success
+ * @retval <0 on failure (e.g. queue full)
  */
 int odp_queue_enq(odp_queue_t queue, odp_event_t ev);
 
@@ -199,7 +204,8 @@  int odp_queue_enq_multi(odp_queue_t queue, odp_event_t ev[], int num);
  *
  * @param queue   Queue handle
  *
- * @return Event handle, or ODP_EVENT_INVALID
+ * @return Event handle
+ * @retval ODP_EVENT_INVALID on failure (e.g. queue empty)
  */
 odp_event_t odp_queue_deq(odp_queue_t queue);
 
@@ -210,10 +216,11 @@  odp_event_t odp_queue_deq(odp_queue_t queue);
  * ODP_QUEUE_TYPE_SCHED type queues (use odp_schedule() instead).
  *
  * @param queue   Queue handle
- * @param events  Event handle array for output
- * @param num     Maximum number of event handles
+ * @param[out] events  Array of event handles for output
+ * @param num     Maximum number of events to dequeue
 
- * @return Number of events written (0 ... num)
+ * @return Number of events actually dequeued (0 ... num)
+ * @retval <0 on failure
  */
 int odp_queue_deq_multi(odp_queue_t queue, odp_event_t events[], int num);