diff --git a/example/ipsec/odp_ipsec.c b/example/ipsec/odp_ipsec.c
index f2fac8a..066dc40 100644
--- a/example/ipsec/odp_ipsec.c
+++ b/example/ipsec/odp_ipsec.c
@@ -683,7 +683,7 @@ pkt_disposition_e do_ipsec_in_classify(odp_packet_t pkt,
 	odph_esphdr_t *esp = NULL;
 	ipsec_cache_entry_t *entry;
 	odp_crypto_op_params_t params;
-	bool posted = 0;
+	odp_bool_t posted = 0;
 
 	/* Default to skip IPsec */
 	*skip = TRUE;
@@ -955,7 +955,7 @@ pkt_disposition_e do_ipsec_out_seq(odp_packet_t pkt,
 				   pkt_ctx_t *ctx)
 {
 	uint8_t *buf = odp_packet_data(pkt);
-	bool posted = 0;
+	odp_bool_t posted = 0;
 
 	/* We were dispatched from atomic queue, assign sequence numbers */
 	if (ctx->ipsec.ah_offset) {
diff --git a/platform/linux-generic/include/api/odp_buffer.h b/platform/linux-generic/include/api/odp_buffer.h
index 0670464..fd0871b 100644
--- a/platform/linux-generic/include/api/odp_buffer.h
+++ b/platform/linux-generic/include/api/odp_buffer.h
@@ -32,6 +32,7 @@ extern "C" {
  * Buffer start address
  *
  * @param buf      Buffer handle
+ * Note: Buffer handle must be valid or the behavior will be undefined.
  *
  * @return Buffer start address
  */
@@ -41,6 +42,7 @@ void *odp_buffer_addr(odp_buffer_t buf);
  * Buffer maximum data size
  *
  * @param buf      Buffer handle
+ * Note: Buffer handle must be valid or the behavior will be undefined.
  *
  * @return Buffer maximum data size
  */
@@ -50,12 +52,12 @@ uint32_t odp_buffer_size(odp_buffer_t buf);
  * Buffer type
  *
  * @param buf      Buffer handle
+ * Note: Buffer handle must be valid or the behavior will be undefined.
  *
  * @return Buffer type
  */
 int odp_buffer_type(odp_buffer_t buf);
 
-#define ODP_BUFFER_TYPE_INVALID (-1) /**< Buffer type invalid */
 #define ODP_BUFFER_TYPE_ANY       0  /**< Buffer that can hold any other
 					  buffer type */
 #define ODP_BUFFER_TYPE_RAW       1  /**< Raw buffer, no additional metadata */
@@ -65,7 +67,9 @@ int odp_buffer_type(odp_buffer_t buf);
 /**
  * Tests if buffer is valid
  *
- * @param buf      Buffer handle
+ * @param buf      Buffer handle (possibly invalid)
+ * Note: This is the only call which accepts invalid buffer handles (any bit
+ * value) without causing undefined behavior.
  *
  * @retval 1 Buffer handle represents a valid buffer.
  * @retval 0 Buffer handle does not represent a valid buffer.
@@ -76,6 +80,7 @@ int odp_buffer_is_valid(odp_buffer_t buf);
  * Buffer pool of the buffer
  *
  * @param buf       Buffer handle
+ * Note: Buffer handle must be valid or the behavior will be undefined.
  *
  * @return Handle of buffer pool buffer belongs to
  */
diff --git a/platform/linux-generic/include/api/odp_buffer_pool.h b/platform/linux-generic/include/api/odp_buffer_pool.h
index 8380ac1..fe917a4 100644
--- a/platform/linux-generic/include/api/odp_buffer_pool.h
+++ b/platform/linux-generic/include/api/odp_buffer_pool.h
@@ -81,8 +81,8 @@ odp_buffer_pool_t odp_buffer_pool_create(const char *name,
  *
  * @param pool    Handle of the buffer pool to be destroyed
  *
- * @retval 0 Success
- * @retval -1 Failure
+ * @retval 0 if successful
+ * @retval <0 on failure
  *
  * @note This routine destroys a previously created buffer pool. This call
  * does not destroy any shared memory object passed to
@@ -117,7 +117,7 @@ typedef struct odp_buffer_pool_info_t {
 	odp_shm_t shm;                    /**< handle of shared memory area
 					     supplied by application to
 					     contain buffer pool, or
-					     ODP_SHM_INVALID if this pool is
+					     ODP_SHM_NULL if this pool is
 					     managed by ODP */
 	odp_buffer_pool_param_t params;   /**< pool parameters */
 } odp_buffer_pool_info_t;
@@ -125,13 +125,13 @@ typedef struct odp_buffer_pool_info_t {
 /**
  * Retrieve information about a buffer pool
  *
- * @param pool         Buffer pool handle
+ * @param pool         Buffer pool handle (possibly invalid)
  *
  * @param[out] info    Receives an odp_buffer_pool_info_t object
  *                     that describes the pool.
  *
- * @retval 0 Success
- * @retval -1 Failure.  Info could not be retrieved.
+ * @retval 0 if successful
+ * @retval <0 on failure. Info could not be retrieved (invalid pool handle)
  */
 
 int odp_buffer_pool_info(odp_buffer_pool_t pool,
@@ -149,17 +149,22 @@ void odp_buffer_pool_print(odp_buffer_pool_t pool);
 
 /**
  * Buffer alloc
+ * Note: the pool handle must be valid or the behavior is undefined.
+ *
+ * The validity of a buffer handle can be checked at any time using
+ * odp_buffer_is_valid()
  *
- * The validity of a buffer can be cheked at any time with odp_buffer_is_valid()
  * @param pool      Pool handle
  *
  * @return Handle of allocated buffer
- * @retval ODP_BUFFER_INVALID  Buffer could not be allocated
+ * @retval ODP_BUFFER_INVALID  Buffer could not be allocated (e.g. pool
+ * exhausted)
  */
 odp_buffer_t odp_buffer_alloc(odp_buffer_pool_t pool);
 
 /**
  * Buffer free
+ * Note: the buffer handle must be valid or the behavior is undefined.
  *
  * @param buf       Buffer handle
  *
diff --git a/platform/linux-generic/include/api/odp_byteorder.h b/platform/linux-generic/include/api/odp_byteorder.h
index 5890011..8e38937 100644
--- a/platform/linux-generic/include/api/odp_byteorder.h
+++ b/platform/linux-generic/include/api/odp_byteorder.h
@@ -24,7 +24,7 @@ extern "C" {
 #include <odp_compiler.h>
 
 /** @defgroup odp_compiler_optim ODP COMPILER / OPTIMIZATION
- *  Macros that check byte order and byte converting operations.
+ *  Macros that check and convert byte order.
  *  @{
  */
 
diff --git a/platform/linux-generic/include/api/odp_classification.h b/platform/linux-generic/include/api/odp_classification.h
index 46189bc..6bca8fc 100644
--- a/platform/linux-generic/include/api/odp_classification.h
+++ b/platform/linux-generic/include/api/odp_classification.h
@@ -79,8 +79,8 @@ typedef enum odp_cos_hdr_flow_fields {
  *
  * @param[in]  name	String intended for debugging purposes.
  *
- * @return		Class of service instance identifier,
- *			or ODP_COS_INVALID on error.
+ * @return		Class of service instance identifier
+ * @retval		ODP_COS_INVALID on failure.
  */
 odp_cos_t odp_cos_create(const char *name);
 
@@ -89,7 +89,8 @@ odp_cos_t odp_cos_create(const char *name);
  *
  * @param[in]	cos_id	class-of-service instance.
  *
- * @return		0 on success, non-zero on error.
+ * @retval		0 if successful
+ * @retval		<0 on failure
  */
 int odp_cos_destroy(odp_cos_t cos_id);
 
@@ -102,7 +103,8 @@ int odp_cos_destroy(odp_cos_t cos_id);
  *				of this specific class of service
  *				will be enqueued.
  *
- * @return			0 on success, non-zero on error.
+ * @retval			0 if successful
+ * @retval			<0 on failure
  */
 int odp_cos_set_queue(odp_cos_t cos_id, odp_queue_t queue_id);
 
@@ -112,7 +114,8 @@ int odp_cos_set_queue(odp_cos_t cos_id, odp_queue_t queue_id);
  * @param[in]	cos_id		class-of-service instance.
  * @param[in]	drop_policy	Desired packet drop policy for this class.
  *
- * @return			0 on success, non-zero on error.
+ * @retval			0 if successful
+ * @retval			<0 on failure
  *
  * @note Optional.
  */
@@ -127,7 +130,8 @@ int odp_cos_set_drop(odp_cos_t cos_id, odp_drop_e drop_policy);
  * @param[in]	qos_table	Values of the Layer-2 QoS header field.
  * @param[in]	cos_table	Class-of-service assigned to each of the
  *				allowed Layer-2 QOS levels.
- * @return			0 on success, non-zero on error.
+ * @retval			0 if successful
+ * @retval			<0 on failure
  */
 int odp_cos_with_l2_priority(odp_pktio_t pktio_in,
 			     uint8_t num_qos,
@@ -146,7 +150,8 @@ int odp_cos_with_l2_priority(odp_pktio_t pktio_in,
  * @param[in]	l3_preference	when true, Layer-3 QoS overrides
  *				L2 QoS when present.
  *
- * @return			0 on success, non-zero on error.
+ * @retval			0 if successful
+ * @retval			<0 on failure
  *
  * @note Optional.
  */
@@ -219,7 +224,8 @@ typedef enum odp_pmr_term {
  *			that must match the value size requirement of the
  *			specific term.
  *
- * @return		Handle of the matching rule or ODP_PMR_INVAL on error
+ * @return		Handle of the matching rule
+ * @retval		ODP_PMR_INVAL on failure
  */
 odp_pmr_t odp_pmr_create_match(odp_pmr_term_e term,
 			       const void *val,
@@ -236,7 +242,8 @@ odp_pmr_t odp_pmr_create_match(odp_pmr_term_e term,
  *			that must match the value size requirement of the
  *			specific term.
  *
- * @return		Handle of the matching rule or ODP_PMR_INVAL on error
+ * @return		Handle of the matching rule
+ * @retval		ODP_PMR_INVAL on failure
  * @note: Range is inclusive [val1..val2].
  */
 odp_pmr_t odp_pmr_create_range(odp_pmr_term_e term,
@@ -248,7 +255,8 @@ odp_pmr_t odp_pmr_create_range(odp_pmr_term_e term,
  *
  * @param[in]	pmr_id	Identifier of the PMR to be destroyed
  *
- * @return		0 on success, non-zero or error.
+ * @retval		0 if successful
+ * @retval		<0 on failure
  */
 int odp_pmr_destroy(odp_pmr_t pmr_id);
 
@@ -259,7 +267,8 @@ int odp_pmr_destroy(odp_pmr_t pmr_id);
  * @param[in]	src_pktio	pktio to which this PMR is to be applied
  * @param[in]	dst_cos		CoS to be assigned by this PMR
  *
- * @return			0 on success, non-zero or error.
+ * @retval		0 if successful
+ * @retval		<0 on failure
  */
 int odp_pktio_pmr_cos(odp_pmr_t pmr_id,
 		      odp_pktio_t src_pktio, odp_cos_t dst_cos);
@@ -272,7 +281,8 @@ int odp_pktio_pmr_cos(odp_pmr_t pmr_id,
  * @param[in]	dst_cos		CoS to be assigned to packets filtered
  *				from src_cos that match pmr_id.
  *
- * @return			0 on success, non-zero on error.
+ * @retval		0 if successful
+ * @retval		<0 on failure
  */
 int odp_cos_pmr_cos(odp_pmr_t pmr_id, odp_cos_t src_cos, odp_cos_t dst_cos);
 
@@ -346,12 +356,10 @@ typedef uint32_t odp_pmr_set_t;
  *				term desired.
  * @param[out]	pmr_set_id	Returned handle to the composite rule set.
  *
- * @return			Return value may be a positive number
- *				indicating the number of terms elements
+ * @return			the number of terms elements
  *				that have been successfully mapped to the
- *				underlying platform classification engine and
- *				may be in the range from 1 to num_terms,
- *				or non-zero for error.
+ *				underlying platform classification engine
+ * @retval                      <0 on failure
  */
 int odp_pmr_match_set_create(int num_terms, odp_pmr_match_t *terms,
 			     odp_pmr_set_t *pmr_set_id);
@@ -369,7 +377,8 @@ int odp_pmr_match_set_create(int num_terms, odp_pmr_match_t *terms,
  * @param[in]	pmr_set_id	A composite rule-set handle
  *				returned when created.
  *
- * @return			0 on success, non-zero on error.
+ * @retval			0 if successful
+ * @retval			<0 on failure
  */
 int odp_pmr_match_set_destroy(odp_pmr_set_t pmr_set_id);
 
@@ -381,7 +390,8 @@ int odp_pmr_match_set_destroy(odp_pmr_set_t pmr_set_id);
  *				set is to be applied
  * @param[in]	dst_cos		CoS to be assigned by this PMR match set
  *
- * @return			0 on success, non-zero or error.
+ * @retval			0 if successful
+ * @retval			<0 on failure
  */
 int odp_pktio_pmr_match_set_cos(odp_pmr_set_t pmr_set_id, odp_pktio_t src_pktio,
 				odp_cos_t dst_cos);
diff --git a/platform/linux-generic/include/api/odp_cpumask.h b/platform/linux-generic/include/api/odp_cpumask.h
index ebff9b0..5c5bcd7 100644
--- a/platform/linux-generic/include/api/odp_cpumask.h
+++ b/platform/linux-generic/include/api/odp_cpumask.h
@@ -79,7 +79,8 @@ void odp_cpumask_clr(odp_cpumask_t *mask, int cpu);
  * Test if cpu is a member of mask
  * @param mask  CPU mask to check if cpu num set or not
  * @param cpu   CPU number
- * @return      non-zero if set otherwise 0
+ * @return      non-zero if set
+ * @retval	0 if not set
  */
 int odp_cpumask_isset(const odp_cpumask_t *mask, int cpu);
 
@@ -134,14 +135,16 @@ void odp_cpumask_copy(odp_cpumask_t *dest, const odp_cpumask_t *src);
 /**
  * Find first bit set in mask
  *
- * @return cpu else -1 if no bits set in cpumask
+ * @return cpu
+ * @retval -1 if no bits set in cpumask
  */
 int odp_cpumask_first(const odp_cpumask_t *mask);
 
 /**
  * Find last bit set in mask
  *
- * @return cpu else -1 if no bits set in cpumask
+ * @return cpu
+ * @retval -1 if no bits set in cpumask
  */
 int odp_cpumask_last(const odp_cpumask_t *mask);
 
@@ -160,7 +163,8 @@ int odp_cpumask_last(const odp_cpumask_t *mask);
  *
  * @param mask        CPU mask to find next cpu in
  * @param cpu         CPU to start from
- * @return cpu found else -1
+ * @return cpu found
+ * @retval -1 if not found
  *
  * @see odp_cpumask_first()
  */
diff --git a/platform/linux-generic/include/api/odp_crypto.h b/platform/linux-generic/include/api/odp_crypto.h
index 337e7cf..2f00f95 100644
--- a/platform/linux-generic/include/api/odp_crypto.h
+++ b/platform/linux-generic/include/api/odp_crypto.h
@@ -218,7 +218,8 @@ typedef struct odp_crypto_compl_status {
  * @param session           Created session else ODP_CRYPTO_SESSION_INVALID
  * @param status            Failure code if unsuccessful
  *
- * @return 0 if successful else -1
+ * @retval 0 if successful
+ * @retval <0 on failure
  */
 int
 odp_crypto_session_create(odp_crypto_session_params_t *params,
@@ -242,11 +243,12 @@ odp_crypto_session_create(odp_crypto_session_params_t *params,
  * @param posted            Pointer to return posted, TRUE for async operation
  * @param completion_event  Event by which the operation results are delivered.
  *
- * @return 0 if successful else -1
+ * @retval 0 if successful
+ * @retval <0 on failure
  */
 int
 odp_crypto_operation(odp_crypto_op_params_t *params,
-		     bool *posted,
+		     odp_bool_t *posted,
 		     odp_buffer_t completion_event);
 
 /**
@@ -281,7 +283,7 @@ odp_crypto_get_operation_compl_status(odp_buffer_t completion_event,
  *
  * @param completion_event  Event containing operation results
  *
- * @return Packet structure where data now resides
+ * @return Handle for packet where data now resides
  */
 odp_packet_t
 odp_crypto_get_operation_compl_packet(odp_buffer_t completion_event);
@@ -305,10 +307,11 @@ odp_crypto_get_operation_compl_ctx(odp_buffer_t completion_event);
  *
  * @todo Define the implication of the use_entropy parameter
  *
- * @return 0 if succesful
+ * @retval 0 if successful
+ * @retval <0 on failure
  */
 int
-odp_hw_random_get(uint8_t *buf, size_t *len, bool use_entropy);
+odp_hw_random_get(uint8_t *buf, size_t *len, odp_bool_t use_entropy);
 
 /**
  * @}
diff --git a/platform/linux-generic/include/api/odp_init.h b/platform/linux-generic/include/api/odp_init.h
index ac856df..4a98717 100644
--- a/platform/linux-generic/include/api/odp_init.h
+++ b/platform/linux-generic/include/api/odp_init.h
@@ -66,8 +66,8 @@ typedef enum odp_log_level {
  * @param[in] level   Log level
  * @param[in] fmt     printf-style message format
  *
- * @return The number of characters logged if succeeded. Otherwise returns
- *         a negative number.
+ * @return The number of characters logged if successful
+ * @retval <0 on failure
  */
 int odp_override_log(odp_log_level_e level, const char *fmt, ...);
 
@@ -109,7 +109,7 @@ typedef struct odp_platform_init_t {
  * interpretation by the ODP API to the implementation.
  *
  * @retval 0 if successful
- * @retval -1 on failure
+ * @retval <0 on failure
  */
 int odp_init_global(odp_init_t *params, odp_platform_init_t *platform_params);
 
@@ -134,7 +134,7 @@ int odp_init_global(odp_init_t *params, odp_platform_init_t *platform_params);
  * @sa odp_term_local() which must have been called prior to this.
  *
  * @retval 0 if successful
- * @retval -1 on failure
+ * @retval <0 on failure
  */
 int odp_term_global(void);
 
@@ -148,7 +148,7 @@ int odp_term_global(void);
  * @sa odp_init_global() which must have been called prior to this.
  *
  * @retval 0 if successful
- * @retval -1 on failure
+ * @retval <0 on failure
  */
 int odp_init_local(void);
 
diff --git a/platform/linux-generic/include/api/odp_packet.h b/platform/linux-generic/include/api/odp_packet.h
index 920a593..b471d07 100644
--- a/platform/linux-generic/include/api/odp_packet.h
+++ b/platform/linux-generic/include/api/odp_packet.h
@@ -88,8 +88,8 @@ void odp_packet_free(odp_packet_t pkt);
  * @param pkt           Packet handle
  * @param len           Packet data length
  *
- * @retval 0 Success
- * @retval Non-zero Failure
+ * @retval 0 if successful
+ * @retval <0 on failure
  *
  * @see odp_packet_buf_len()
  */
@@ -279,7 +279,7 @@ void *odp_packet_push_head(odp_packet_t pkt, uint32_t len);
  * @param pkt  Packet handle
  * @param len  Number of bytes to pull the head (0 ... seg_len - 1)
  *
- * @return The new data pointer, or NULL in case of an error.
+ * @return The new data pointer
  * @retval NULL  Requested offset exceeds packet segment length
  *
  * @see odp_packet_seg_len(), odp_packet_push_head()
@@ -391,7 +391,7 @@ odp_buffer_pool_t odp_packet_pool(odp_packet_t pkt);
  * @param pkt   Packet handle
  *
  * @return Packet interface handle
- * @retval ODP_PKTIO_INVALID  Packet was not received
+ * @retval ODP_PKTIO_INVALID  Packet was not received on any interface
  */
 odp_pktio_t odp_packet_input(odp_packet_t pkt);
 
@@ -451,8 +451,8 @@ void odp_packet_user_u64_set(odp_packet_t pkt, uint64_t ctx);
  * @param[out] len      Number of data bytes remaining in the segment (output).
  *                      Ignored when NULL.
  *
- * @return  Layer 2 start pointer, or NULL when packet does not contain a valid
- *          L2 header.
+ * @return  Layer 2 start pointer
+ * @retval  NULL packet does not contain a valid L2 header
  *
  * @see odp_packet_l2_offset(), odp_packet_l2_offset_set(), odp_packet_has_l2()
  */
@@ -469,8 +469,8 @@ void *odp_packet_l2_ptr(odp_packet_t pkt, uint32_t *len);
  *
  * @param pkt  Packet handle
  *
- * @return  Layer 2 start offset, or ODP_PACKET_OFFSET_INVALID when packet does
- *          not contain a valid L2 header.
+ * @return  Layer 2 start offset
+ * @retval ODP_PACKET_OFFSET_INVALID packet does not contain a valid L2 header
  *
  * @see odp_packet_l2_offset_set(), odp_packet_has_l2()
  */
@@ -486,8 +486,8 @@ uint32_t odp_packet_l2_offset(odp_packet_t pkt);
  * @param pkt     Packet handle
  * @param offset  Layer 2 start offset (0 ... odp_packet_len()-1)
  *
- * @retval 0 Success
- * @retval Non-zero Failure
+ * @retval 0 if successful
+ * @retval <0 on failure
  */
 int odp_packet_l2_offset_set(odp_packet_t pkt, uint32_t offset);
 
@@ -501,8 +501,8 @@ int odp_packet_l2_offset_set(odp_packet_t pkt, uint32_t offset);
  * @param[out] len      Number of data bytes remaining in the segment (output).
  *                      Ignored when NULL.
  *
- * @return  Layer 3 start pointer, or NULL when packet does not contain a valid
- *          L3 header.
+ * @return  Layer 3 start pointer
+ * @retval NULL packet does not contain a valid L3 header
  *
  * @see odp_packet_l3_offset(), odp_packet_l3_offset_set(), odp_packet_has_l3()
  */
@@ -536,8 +536,8 @@ uint32_t odp_packet_l3_offset(odp_packet_t pkt);
  * @param pkt     Packet handle
  * @param offset  Layer 3 start offset (0 ... odp_packet_len()-1)
  *
- * @retval 0 Success
- * @retval Non-zero Failure
+ * @retval 0 if successful
+ * @retval <0 on failure
  */
 int odp_packet_l3_offset_set(odp_packet_t pkt, uint32_t offset);
 
@@ -551,8 +551,8 @@ int odp_packet_l3_offset_set(odp_packet_t pkt, uint32_t offset);
  * @param[out] len      Number of data bytes remaining in the segment (output).
  *                      Ignored when NULL.
  *
- * @return  Layer 4 start pointer, or NULL when packet does not contain a valid
- *          L4 header.
+ * @return  Layer 4 start pointer
+ * @retval NULL packet does not contain a valid L4 header
  *
  * @see odp_packet_l4_offset(), odp_packet_l4_offset_set(), odp_packet_has_l4()
  */
@@ -569,8 +569,8 @@ void *odp_packet_l4_ptr(odp_packet_t pkt, uint32_t *len);
  *
  * @param pkt  Packet handle
  *
- * @return  Layer 4 start offset, or ODP_PACKET_OFFSET_INVALID when packet does
- *          not contain a valid L4 header.
+ * @return  Layer 4 start offset
+ * @retval ODP_PACKET_OFFSET_INVALID packet does not contain a valid L4 header
  *
  * @see odp_packet_l4_offset_set(), odp_packet_has_l4()
  */
@@ -586,8 +586,8 @@ uint32_t odp_packet_l4_offset(odp_packet_t pkt);
  * @param pkt     Packet handle
  * @param offset  Layer 4 start offset (0 ... odp_packet_len()-1)
  *
- * @retval 0 Success
- * @retval Non-zero Failure
+ * @retval 0 on success
+ * @retval <0 on failure
  */
 int odp_packet_l4_offset_set(odp_packet_t pkt, uint32_t offset);
 
@@ -645,7 +645,8 @@ odp_packet_seg_t odp_packet_last_seg(odp_packet_t pkt);
  * @param pkt   Packet handle
  * @param seg   Current segment handle
  *
- * @return Handle to the next segment, or ODP_PACKET_SEG_INVALID
+ * @return Handle to the next segment
+ * @retval ODP_PACKET_SEG_INVALID if there are no more segments
  */
 odp_packet_seg_t odp_packet_next_seg(odp_packet_t pkt, odp_packet_seg_t seg);
 
@@ -665,7 +666,8 @@ odp_packet_seg_t odp_packet_next_seg(odp_packet_t pkt, odp_packet_seg_t seg);
  * @param pkt  Packet handle
  * @param seg  Segment handle
  *
- * @return  Start address of the segment, or NULL on an error
+ * @return  Start address of the segment
+ * @retval NULL on failure
  *
  * @see odp_packet_seg_buf_len()
  */
@@ -693,7 +695,8 @@ uint32_t odp_packet_seg_buf_len(odp_packet_t pkt, odp_packet_seg_t seg);
  * @param pkt  Packet handle
  * @param seg  Segment handle
  *
- * @return  Pointer to the segment data, or NULL on an error
+ * @return  Pointer to the segment data
+ * @retval NULL on failure
  *
  * @see odp_packet_seg_data_len()
  */
@@ -735,7 +738,8 @@ uint32_t odp_packet_seg_data_len(odp_packet_t pkt, odp_packet_seg_t seg);
  * @param offset  Byte offset into the packet
  * @param len     Number of bytes to add into the offset
  *
- * @return New packet handle, or ODP_PACKET_INVALID in case of an error.
+ * @return New packet handle
+ * @retval ODP_PACKET_INVALID on failure
  */
 odp_packet_t odp_packet_add_data(odp_packet_t pkt, uint32_t offset,
 				 uint32_t len);
@@ -753,7 +757,8 @@ odp_packet_t odp_packet_add_data(odp_packet_t pkt, uint32_t offset,
  * @param offset  Byte offset into the packet
  * @param len     Number of bytes to remove from the offset
  *
- * @return New packet handle, or ODP_PACKET_INVALID in case of an error.
+ * @return New packet handle
+ * @retval ODP_PACKET_INVALID on failure
  */
 odp_packet_t odp_packet_rem_data(odp_packet_t pkt, uint32_t offset,
 				 uint32_t len);
@@ -776,7 +781,8 @@ odp_packet_t odp_packet_rem_data(odp_packet_t pkt, uint32_t offset,
  * @param pkt   Packet handle
  * @param pool  Buffer pool for allocation of the new packet.
  *
- * @return Handle to the copy of the packet, or ODP_PACKET_INVALID
+ * @return Handle to the copy of the packet
+ * @retval ODP_PACKET_INVALID on failure
  */
 odp_packet_t odp_packet_copy(odp_packet_t pkt, odp_buffer_pool_t pool);
 
@@ -791,8 +797,8 @@ odp_packet_t odp_packet_copy(odp_packet_t pkt, odp_buffer_pool_t pool);
  * @param len    Number of bytes to copy
  * @param dst    Destination address
  *
- * @retval 0 Success
- * @retval Non-zero Failure
+ * @retval 0 on success
+ * @retval <0 on failure
  */
 int odp_packet_copydata_out(odp_packet_t pkt, uint32_t offset,
 			    uint32_t len, void *dst);
@@ -809,8 +815,8 @@ int odp_packet_copydata_out(odp_packet_t pkt, uint32_t offset,
  * @param len    Number of bytes to copy
  * @param src    Source address
  *
- * @retval 0 Success
- * @retval Non-zero Failure
+ * @retval 0 on success
+ * @retval <0 on failure
  */
 int odp_packet_copydata_in(odp_packet_t pkt, uint32_t offset,
 			   uint32_t len, const void *src);
diff --git a/platform/linux-generic/include/api/odp_packet_flags.h b/platform/linux-generic/include/api/odp_packet_flags.h
index 24c4065..399a0bf 100644
--- a/platform/linux-generic/include/api/odp_packet_flags.h
+++ b/platform/linux-generic/include/api/odp_packet_flags.h
@@ -32,7 +32,8 @@ extern "C" {
  * Checks all error flags at once.
  *
  * @param pkt Packet handle
- * @return 1 if packet has errors, 0 otherwise
+ * @retval 1 if packet has errors
+ * @retval 0 if packet has no errors
  */
 int odp_packet_error(odp_packet_t pkt);
 
@@ -40,7 +41,8 @@ int odp_packet_error(odp_packet_t pkt);
  * Check if error was 'frame length' error
  *
  * @param pkt Packet handle
- * @return 1 if frame length error detected, 0 otherwise
+ * @retval 1 if frame length error detected
+ * @retval 0 if frame length error not detected
  */
 int odp_packet_errflag_frame_len(odp_packet_t pkt);
 
@@ -48,7 +50,8 @@ int odp_packet_errflag_frame_len(odp_packet_t pkt);
  * Check for L2 header, e.g. ethernet
  *
  * @param pkt Packet handle
- * @return 1 if packet contains a valid & known L2 header, 0 otherwise
+ * @retval 1 if packet contains a valid & known L2 header
+ * @retval 0 if packet does not contain a valid & known L2 header
  */
 int odp_packet_has_l2(odp_packet_t pkt);
 
@@ -56,7 +59,8 @@ int odp_packet_has_l2(odp_packet_t pkt);
  * Check for L3 header, e.g. IPv4, IPv6
  *
  * @param pkt Packet handle
- * @return 1 if packet contains a valid & known L3 header, 0 otherwise
+ * @retval 1 if packet contains a valid & known L3 header
+ * @retval 0 if packet does not contain a valid & known L3 header
  */
 int odp_packet_has_l3(odp_packet_t pkt);
 
@@ -64,7 +68,8 @@ int odp_packet_has_l3(odp_packet_t pkt);
  * Check for L4 header, e.g. UDP, TCP, SCTP (also ICMP)
  *
  * @param pkt Packet handle
- * @return 1 if packet contains a valid & known L4 header, 0 otherwise
+ * @retval 1 if packet contains a valid & known L4 header
+ * @retval 0 if packet does not contain a valid & known L4 header
  */
 int odp_packet_has_l4(odp_packet_t pkt);
 
@@ -72,7 +77,8 @@ int odp_packet_has_l4(odp_packet_t pkt);
  * Check for Ethernet header
  *
  * @param pkt Packet handle
- * @return 1 if packet contains a valid eth header, 0 otherwise
+ * @retval 1 if packet contains a valid eth header
+ * @retval 0 if packet does not contain a valid & known eth header
  */
 int odp_packet_has_eth(odp_packet_t pkt);
 
@@ -80,7 +86,8 @@ int odp_packet_has_eth(odp_packet_t pkt);
  * Check for jumbo frame
  *
  * @param pkt Packet handle
- * @return 1 if packet contains jumbo frame, 0 otherwise
+ * @retval 1 if packet contains a jumbo frame
+ * @retval 0 if packet does not contain a jumbo frame
  */
 int odp_packet_has_jumbo(odp_packet_t pkt);
 
@@ -88,7 +95,8 @@ int odp_packet_has_jumbo(odp_packet_t pkt);
  * Check for VLAN
  *
  * @param pkt Packet handle
- * @return 1 if packet contains a VLAN header, 0 otherwise
+ * @retval 1 if packet contains a VLAN header
+ * @retval 0 if packet does not contain a VLAN header
  */
 int odp_packet_has_vlan(odp_packet_t pkt);
 
@@ -96,7 +104,8 @@ int odp_packet_has_vlan(odp_packet_t pkt);
  * Check for VLAN QinQ (stacked VLAN)
  *
  * @param pkt Packet handle
- * @return 1 if packet contains a VLAN QinQ header, 0 otherwise
+ * @retval 1 if packet contains a VLAN QinQ header
+ * @retval 0 if packet does not contain a VLAN QinQ header
  */
 int odp_packet_has_vlan_qinq(odp_packet_t pkt);
 
@@ -104,7 +113,8 @@ int odp_packet_has_vlan_qinq(odp_packet_t pkt);
  * Check for ARP
  *
  * @param pkt Packet handle
- * @return 1 if packet contains an ARP header, 0 otherwise
+ * @retval 1 if packet contains an ARP message
+ * @retval 0 if packet does not contain an ARP message
  */
 int odp_packet_has_arp(odp_packet_t pkt);
 
@@ -112,7 +122,8 @@ int odp_packet_has_arp(odp_packet_t pkt);
  * Check for IPv4
  *
  * @param pkt Packet handle
- * @return 1 if packet contains an IPv4 header, 0 otherwise
+ * @retval 1 if packet contains an IPv4 header
+ * @retval 0 if packet does not contain an IPv4 header
  */
 int odp_packet_has_ipv4(odp_packet_t pkt);
 
@@ -120,7 +131,8 @@ int odp_packet_has_ipv4(odp_packet_t pkt);
  * Check for IPv6
  *
  * @param pkt Packet handle
- * @return 1 if packet contains an IPv6 header, 0 otherwise
+ * @retval 1 if packet contains an IPv6 header
+ * @retval 0 if packet does not contain an IPv6 header
  */
 int odp_packet_has_ipv6(odp_packet_t pkt);
 
@@ -128,7 +140,8 @@ int odp_packet_has_ipv6(odp_packet_t pkt);
  * Check for IP fragment
  *
  * @param pkt Packet handle
- * @return 1 if packet is an IP fragment, 0 otherwise
+ * @retval 1 if packet is an IP fragment
+ * @retval 0 if packet is not an IP fragment
  */
 int odp_packet_has_ipfrag(odp_packet_t pkt);
 
@@ -136,7 +149,8 @@ int odp_packet_has_ipfrag(odp_packet_t pkt);
  * Check for IP options
  *
  * @param pkt Packet handle
- * @return 1 if packet contains IP options, 0 otherwise
+ * @retval 1 if packet contains IP options
+ * @retval 0 if packet does not contain IP options
  */
 int odp_packet_has_ipopt(odp_packet_t pkt);
 
@@ -144,7 +158,8 @@ int odp_packet_has_ipopt(odp_packet_t pkt);
  * Check for IPSec
  *
  * @param pkt Packet handle
- * @return 1 if packet requires IPSec processing, 0 otherwise
+ * @retval 1 if packet requires IPSec processing
+ * @retval 0 if packet does not require IPSec processing
  */
 int odp_packet_has_ipsec(odp_packet_t pkt);
 
@@ -152,7 +167,8 @@ int odp_packet_has_ipsec(odp_packet_t pkt);
  * Check for UDP
  *
  * @param pkt Packet handle
- * @return 1 if packet contains a UDP header, 0 otherwise
+ * @retval 1 if packet contains a UDP header
+ * @retval 0 if packet does not contain a UDP header
  */
 int odp_packet_has_udp(odp_packet_t pkt);
 
@@ -160,7 +176,8 @@ int odp_packet_has_udp(odp_packet_t pkt);
  * Check for TCP
  *
  * @param pkt Packet handle
- * @return 1 if packet contains a TCP header, 0 otherwise
+ * @retval 1 if packet contains a TCP header
+ * @retval 0 if packet does not contain a TCP header
  */
 int odp_packet_has_tcp(odp_packet_t pkt);
 
@@ -168,7 +185,8 @@ int odp_packet_has_tcp(odp_packet_t pkt);
  * Check for SCTP
  *
  * @param pkt Packet handle
- * @return 1 if packet contains an SCTP header, 0 otherwise
+ * @retval 1 if packet contains a SCTP header
+ * @retval 0 if packet does not contain a SCTP header
  */
 int odp_packet_has_sctp(odp_packet_t pkt);
 
@@ -176,7 +194,8 @@ int odp_packet_has_sctp(odp_packet_t pkt);
  * Check for ICMP
  *
  * @param pkt Packet handle
- * @return 1 if packet contains an ICMP header, 0 otherwise
+ * @retval 1 if packet contains an ICMP header
+ * @retval 0 if packet does not contain an ICMP header
  */
 int odp_packet_has_icmp(odp_packet_t pkt);
 
diff --git a/platform/linux-generic/include/api/odp_packet_io.h b/platform/linux-generic/include/api/odp_packet_io.h
index 4835f4d..1a770b6 100644
--- a/platform/linux-generic/include/api/odp_packet_io.h
+++ b/platform/linux-generic/include/api/odp_packet_io.h
@@ -40,7 +40,8 @@ extern "C" {
  * @param pool   Pool from which to allocate buffers for storing packets
  *               received over this packet IO
  *
- * @return ODP packet IO handle or ODP_PKTIO_INVALID on error
+ * @return ODP packet IO handle
+ * @retval ODP_PKTIO_INVALID on failure
  *
  * @note dev name loop is specially pktio reserved name for
  *	 device used for testing. Usually it's loop back
@@ -53,7 +54,8 @@ odp_pktio_t odp_pktio_open(const char *dev, odp_buffer_pool_t pool);
  *
  * @param id  ODP packet IO handle
  *
- * @return 0 on success or -1 on error
+ * @retval 0 on success
+ * @retval <0 on failure
  */
 int odp_pktio_close(odp_pktio_t id);
 
@@ -62,7 +64,8 @@ int odp_pktio_close(odp_pktio_t id);
  *
  * @param dev Packet IO device name
  *
- * @return ODP packet IO handle or ODP_PKTIO_INVALID
+ * @return ODP packet IO handle
+ * @retval ODP_PKTIO_INVALID on failure
  */
 odp_pktio_t odp_pktio_lookup(const char *dev);
 
@@ -73,7 +76,8 @@ odp_pktio_t odp_pktio_lookup(const char *dev);
  * @param pkt_table[] Storage for received packets (filled by function)
  * @param len         Length of pkt_table[], i.e. max number of pkts to receive
  *
- * @return Number of packets received or -1 on error
+ * @return Number of packets received
+ * @retval <0 on failure
  */
 int odp_pktio_recv(odp_pktio_t id, odp_packet_t pkt_table[], unsigned len);
 
@@ -84,7 +88,8 @@ int odp_pktio_recv(odp_pktio_t id, odp_packet_t pkt_table[], unsigned len);
  * @param pkt_table[]  Array of packets to send
  * @param len          length of pkt_table[]
  *
- * @return Number of packets sent or -1 on error
+ * @return Number of packets sent
+ * @retval <0 on failure
  */
 int odp_pktio_send(odp_pktio_t id, odp_packet_t pkt_table[], unsigned len);
 
@@ -93,7 +98,8 @@ int odp_pktio_send(odp_pktio_t id, odp_packet_t pkt_table[], unsigned len);
  *
  * @param id	ODP packet IO handle
  * @param queue default input queue set
- * @return  0 on success or -1 on error
+ * @retval  0 on success
+ * @retval <0 on failure
  */
 int odp_pktio_inq_setdef(odp_pktio_t id, odp_queue_t queue);
 
@@ -102,7 +108,8 @@ int odp_pktio_inq_setdef(odp_pktio_t id, odp_queue_t queue);
  *
  * @param id  ODP packet IO handle
  *
- * @return Default input queue set or ODP_QUEUE_INVALID on error
+ * @return Default input queue set
+ * @retval ODP_QUEUE_INVALID on failure
  */
 odp_queue_t odp_pktio_inq_getdef(odp_pktio_t id);
 
@@ -111,7 +118,8 @@ odp_queue_t odp_pktio_inq_getdef(odp_pktio_t id);
  *
  * @param id  ODP packet IO handle
  *
- * @return 0 on success or -1 on error
+ * @retval 0 on success
+ * @retval <0 on failure
  */
 int odp_pktio_inq_remdef(odp_pktio_t id);
 
@@ -120,7 +128,8 @@ int odp_pktio_inq_remdef(odp_pktio_t id);
  *
  * @param id ODP packet IO handle
  *
- * @return Default out queue or ODP_QUEUE_INVALID on error
+ * @return Default out queue
+ * @retval ODP_QUEUE_INVALID on failure
  */
 odp_queue_t odp_pktio_outq_getdef(odp_pktio_t id);
 
@@ -129,8 +138,8 @@ odp_queue_t odp_pktio_outq_getdef(odp_pktio_t id);
  *
  * @param[in] id  ODP packet IO handle.
  *
- * @retval MTU value >0 on success.
- * @retval -1 on any error or not existance pktio id.
+ * @return MTU value on success
+ * @retval <0 on failure
  */
 int odp_pktio_mtu(odp_pktio_t id);
 
@@ -140,8 +149,8 @@ int odp_pktio_mtu(odp_pktio_t id);
  * @param[in] id	ODP packet IO handle.
  * @param[in] enable	1 to enable, 0 to disable.
  *
- * @retval 0 on success.
- * @retval non-zero on any error.
+ * @retval 0 on success
+ * @retval <0 on failure
  */
 int odp_pktio_promisc_mode_set(odp_pktio_t id, odp_bool_t enable);
 
@@ -152,7 +161,7 @@ int odp_pktio_promisc_mode_set(odp_pktio_t id, odp_bool_t enable);
  *
  * @retval  1 if promiscuous mode is enabled.
  * @retval  0 if promiscuous mode is disabled.
- * @retval -1 on any error.
+ * @retval <0 on failure
 */
 int odp_pktio_promisc_mode(odp_pktio_t id);
 
@@ -163,9 +172,10 @@ int odp_pktio_promisc_mode(odp_pktio_t id);
  * @param[out]	mac_addr  Storage for MAC address of the packet IO interface.
  * @param	addr_size Storage size for the address
  *
- * @retval Number of bytes written on success, 0 on failure.
+ * @return Number of bytes written on success
+ * @retval <0 on failure
  */
-size_t odp_pktio_mac_addr(odp_pktio_t id, void *mac_addr,
+int odp_pktio_mac_addr(odp_pktio_t id, void *mac_addr,
 			  size_t addr_size);
 
 /**
@@ -177,7 +187,8 @@ size_t odp_pktio_mac_addr(odp_pktio_t id, void *mac_addr,
  *				unless overridden by subsequent
  *				header-based filters.
  *
- * @return			0 on success, non-zero on error.
+ * @retval			0 on success
+ * @retval			<0 on failure
  */
 int odp_pktio_default_cos_set(odp_pktio_t pktio_in, odp_cos_t default_cos);
 
@@ -189,7 +200,8 @@ int odp_pktio_default_cos_set(odp_pktio_t pktio_in, odp_cos_t default_cos);
  *				at the pktio_in ingress port
  *				that contain an error.
  *
- * @return			0 on success, non-zero on error.
+ * @retval			0 on success
+ * @retval			<0 on failure
  *
  * @note Optional.
  */
@@ -201,7 +213,8 @@ int odp_pktio_error_cos_set(odp_pktio_t pktio_in, odp_cos_t error_cos);
  * @param[in]	pktio_in	Ingress port identifier.
  * @param[in]	offset		Number of bytes the classifier must skip.
  *
- * @return			0 on success, non-zero on error.
+ * @retval			0 on success
+ * @retval			<0 on failure
  * @note  Optional.
  *
  */
@@ -216,7 +229,8 @@ int odp_pktio_skip_set(odp_pktio_t pktio_in, uint32_t offset);
  *				Must not exceed the implementation
  *				defined ODP_PACKET_MAX_HEADROOM.
  *
- * @return			0 on success, non-zero on error.
+ * @retval			0 on success
+ * @retval			<0 on failure
  *
  * @note Optional.
  */
diff --git a/platform/linux-generic/include/api/odp_queue.h b/platform/linux-generic/include/api/odp_queue.h
index b0f7185..25633e0 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 buf     Buffer handle
  *
- * @return 0 if succesful
+ * @retval 0 on success
+ * @retval <0 on failure
  */
 int odp_queue_enq(odp_queue_t queue, odp_buffer_t buf);
 
@@ -187,7 +192,8 @@ int odp_queue_enq(odp_queue_t queue, odp_buffer_t buf);
  * @param buf     Buffer handles
  * @param num     Number of buffer handles
  *
- * @return 0 if succesful
+ * @retval 0 on success
+ * @retval <0 on failure
  */
 int odp_queue_enq_multi(odp_queue_t queue, odp_buffer_t buf[], int num);
 
@@ -199,7 +205,8 @@ int odp_queue_enq_multi(odp_queue_t queue, odp_buffer_t buf[], int num);
  *
  * @param queue   Queue handle
  *
- * @return Buffer handle, or ODP_BUFFER_INVALID
+ * @return Buffer handle
+ * @retval ODP_BUFFER_INVALID on failure
  */
 odp_buffer_t odp_queue_deq(odp_queue_t queue);
 
diff --git a/platform/linux-generic/include/api/odp_schedule.h b/platform/linux-generic/include/api/odp_schedule.h
index cdf6705..36fbba3 100644
--- a/platform/linux-generic/include/api/odp_schedule.h
+++ b/platform/linux-generic/include/api/odp_schedule.h
@@ -59,7 +59,8 @@ uint64_t odp_schedule_wait_time(uint64_t ns);
  *                Use odp_schedule_wait_time() to convert time to other wait
  *                values.
  *
- * @return Next highest priority buffer, or ODP_BUFFER_INVALID
+ * @return Next highest priority buffer
+ * @retval ODP_BUFFER_INVALID on timeout
  */
 odp_buffer_t odp_schedule(odp_queue_t *from, uint64_t wait);
 
diff --git a/platform/linux-generic/include/api/odp_shared_memory.h b/platform/linux-generic/include/api/odp_shared_memory.h
index f70db5a..78d108a 100644
--- a/platform/linux-generic/include/api/odp_shared_memory.h
+++ b/platform/linux-generic/include/api/odp_shared_memory.h
@@ -59,7 +59,8 @@ typedef struct odp_shm_info_t {
  * @param[in] flags  Shared memory parameter flags (ODP_SHM_*).
  *                   Default value is 0.
  *
- * @return Pointer to the reserved block, or NULL
+ * @return Handle of the reserved block
+ * @retval NULL on failure
  */
 odp_shm_t odp_shm_reserve(const char *name, uint64_t size, uint64_t align,
 			  uint32_t flags);
@@ -72,9 +73,9 @@ odp_shm_t odp_shm_reserve(const char *name, uint64_t size, uint64_t align,
  *
  * @param[in] shm Block handle
  *
- * @retval 0 if the handle is already free
+ * @retval 0 if the handle is already free (FIXME how can we know this?)
  * @retval 0 if the handle free succeeds
- * @retval -1 on failure to free the handle
+ * @retval <0 on failure to free the handle
  */
 int odp_shm_free(odp_shm_t shm);
 
@@ -84,7 +85,7 @@ int odp_shm_free(odp_shm_t shm);
  * @param[in] name   Name of the block
  *
  * @return A handle to the block if it is found by name
- * @retval #ODP_SHM_INVALID if the block is not found
+ * @retval ODP_SHM_INVALID on failure
  */
 odp_shm_t odp_shm_lookup(const char *name);
 
@@ -94,7 +95,8 @@ odp_shm_t odp_shm_lookup(const char *name);
  *
  * @param[in] shm   Block handle
  *
- * @return Memory block address, or NULL on error
+ * @return Memory block address
+ * @retval NULL on failure (FIXME: when?)
  */
 void *odp_shm_addr(odp_shm_t shm);
 
@@ -105,7 +107,8 @@ void *odp_shm_addr(odp_shm_t shm);
  * @param[in]  shm   Block handle
  * @param[out] info  Block info pointer for output
  *
- * @return 0 on success, otherwise non-zero
+ * @retval 0 on success
+ * @retval <0 on failure
  */
 int odp_shm_info(odp_shm_t shm, odp_shm_info_t *info);
 
diff --git a/platform/linux-generic/include/api/odp_timer.h b/platform/linux-generic/include/api/odp_timer.h
index 69402ef..c8c3270 100644
--- a/platform/linux-generic/include/api/odp_timer.h
+++ b/platform/linux-generic/include/api/odp_timer.h
@@ -112,8 +112,8 @@ typedef struct {
  * @param name       Name of the timer pool. The string will be copied.
  * @param params     Timer pool parameters. The content will be copied.
  *
- * @return Timer pool handle if successful, otherwise ODP_TIMER_POOL_INVALID
- * and errno set
+ * @return Timer pool handle on success
+ * @retval ODP_TIMER_POOL_INVALID on failure and errno set
  */
 odp_timer_pool_t
 odp_timer_pool_create(const char *name,
@@ -185,8 +185,8 @@ typedef struct {
  * @param tpid Timer pool identifier
  * @param[out] info Pointer to information buffer
  *
- * @retval 0 Success
- * @retval -1 Failure. Info could not be retrieved.
+ * @retval 0 on success
+ * @retval <0 on failure. Info could not be retrieved.
  */
 int odp_timer_pool_info(odp_timer_pool_t tpid,
 			odp_timer_pool_info_t *info);
@@ -202,8 +202,8 @@ int odp_timer_pool_info(odp_timer_pool_t tpid,
  * @param queue    Destination queue for timeout notifications
  * @param user_ptr User defined pointer or NULL to be copied to timeouts
  *
- * @return Timer handle if successful, otherwise ODP_TIMER_INVALID and
- *	   errno set.
+ * @return Timer handle on success
+ * @retval ODP_TIMER_INVALID on failure and errno set.
  */
 odp_timer_t odp_timer_alloc(odp_timer_pool_t tpid,
 			    odp_queue_t queue,
@@ -218,7 +218,8 @@ odp_timer_t odp_timer_alloc(odp_timer_pool_t tpid,
  * responsibility of the application to handle this timeout when it is received.
  *
  * @param tim      Timer handle
- * @return Buffer handle of timeout buffer or ODP_BUFFER_INVALID
+ * @return Buffer handle of timeout buffer
+ * @retval ODP_BUFFER_INVALID on failure
  */
 odp_buffer_t odp_timer_free(odp_timer_t tim);
 
@@ -292,8 +293,8 @@ int odp_timer_set_rel(odp_timer_t tim,
  *
  * @param tim     Timer
  * @param[out] tmo_buf Pointer to a buffer variable
- * @retval 0  Success, active timer cancelled, timeout returned in '*tmo_buf'
- * @retval -1 Failure, timer already expired (or inactive)
+ * @retval 0 on success, active timer cancelled, timeout returned in '*tmo_buf'
+ * @retval <0 on failure, timer already expired (or inactive)
  */
 int odp_timer_cancel(odp_timer_t tim, odp_buffer_t *tmo_buf);
 
diff --git a/platform/linux-generic/odp_crypto.c b/platform/linux-generic/odp_crypto.c
index 2f95cbe..ded3b62 100644
--- a/platform/linux-generic/odp_crypto.c
+++ b/platform/linux-generic/odp_crypto.c
@@ -343,7 +343,7 @@ odp_crypto_session_create(odp_crypto_session_params_t *params,
 
 int
 odp_crypto_operation(odp_crypto_op_params_t *params,
-		     bool *posted,
+		     odp_bool_t *posted,
 		     odp_buffer_t completion_event)
 {
 	enum crypto_alg_err rc_cipher = ODP_CRYPTO_ALG_ERR_NONE;
@@ -423,7 +423,7 @@ odp_crypto_init_global(void)
 }
 
 int
-odp_hw_random_get(uint8_t *buf, size_t *len, bool use_entropy ODP_UNUSED)
+odp_hw_random_get(uint8_t *buf, size_t *len, odp_bool_t use_entropy ODP_UNUSED)
 {
 	int rc;
 	rc = RAND_bytes(buf, *len);
diff --git a/platform/linux-generic/odp_packet_io.c b/platform/linux-generic/odp_packet_io.c
index 0efa3d0..c51098f 100644
--- a/platform/linux-generic/odp_packet_io.c
+++ b/platform/linux-generic/odp_packet_io.c
@@ -797,18 +797,18 @@ int odp_pktio_promisc_mode(odp_pktio_t id)
 }
 
 
-size_t odp_pktio_mac_addr(odp_pktio_t id, void *mac_addr,
+int odp_pktio_mac_addr(odp_pktio_t id, void *mac_addr,
 		       size_t addr_size)
 {
 	pktio_entry_t *entry;
 
 	if (addr_size < ETH_ALEN)
-		return 0;
+		return -1;
 
 	entry = get_pktio_entry(id);
 	if (entry == NULL) {
 		ODP_DBG("pktio entry %d does not exist\n", id);
-		return 0;
+		return -1;
 	}
 
 	lock_entry(entry);
diff --git a/test/validation/crypto/odp_crypto_test_async_inp.c b/test/validation/crypto/odp_crypto_test_async_inp.c
index 96d4c3f..1db7844 100644
--- a/test/validation/crypto/odp_crypto_test_async_inp.c
+++ b/test/validation/crypto/odp_crypto_test_async_inp.c
@@ -34,7 +34,7 @@ static void alg_test(enum odp_crypto_op op,
 	odp_crypto_session_t session;
 	int rc;
 	enum odp_crypto_ses_create_err status;
-	bool posted;
+	odp_bool_t posted;
 	odp_buffer_t compl_event;
 
 	odp_queue_t compl_queue = odp_queue_lookup("crypto-out");
diff --git a/test/validation/crypto/odp_crypto_test_sync_inp.c b/test/validation/crypto/odp_crypto_test_sync_inp.c
index f37ad54..5082f13 100644
--- a/test/validation/crypto/odp_crypto_test_sync_inp.c
+++ b/test/validation/crypto/odp_crypto_test_sync_inp.c
@@ -23,7 +23,7 @@ static void alg_test(enum odp_crypto_op op,
 	odp_crypto_session_t session;
 	int rc;
 	enum odp_crypto_ses_create_err status;
-	bool posted;
+	odp_bool_t posted;
 
 	odp_queue_t compl_queue = odp_queue_lookup("crypto-out");
 	CU_ASSERT(compl_queue != ODP_QUEUE_INVALID);
