Clean Doxygen warnings

Cleaned warnings on include, include/helper and test/example. Used
@internal and @private to mark documentation that should not go
into ODP API docs.

Doxyfile.in needs INTERNAL_DOCS = YES to suppress warnings
(of @internal), but it should be set "NO" for "official"
documentation generation.

Signed-off-by: Petri Savolainen <petri.savolainen@linaro.org>

22 files changed, 223 insertions, 67 deletions

diff --git a/include/helper/odp_eth.h b/include/helper/odp_eth.h
index d1cb33bf..401b915c 100644
--- a/include/helper/odp_eth.h
+++ b/include/helper/odp_eth.h
@@ -23,42 +23,47 @@ extern "C" {
 #include <odp_align.h>
 #include <odp_debug.h>
 
-#define ODP_ETHADDR_LEN     6
-#define ODP_ETHHDR_LEN      14
-#define ODP_VLANHDR_LEN     4
-#define ODP_ETH_LEN_MIN     60   /* exclude 4B CRC/FCS */
-#define ODP_ETH_LEN_MIN_CRC 64   /* include 4B CRC/FCS */
-#define ODP_ETH_LEN_MAX     1514 /* exclude 4B CRC/FCS */
-#define ODP_ETH_LEN_MAX_CRC 1518 /* include 4B CRC/FCS */
+#define ODP_ETHADDR_LEN     6    /**< Ethernet address length */
+#define ODP_ETHHDR_LEN      14   /**< Ethernet header length */
+#define ODP_VLANHDR_LEN     4    /**< VLAN header length */
+#define ODP_ETH_LEN_MIN     60   /**< Min frame length (excl. CRC 4 bytes) */
+#define ODP_ETH_LEN_MIN_CRC 64   /**< Min frame length (incl. CRC 4 bytes) */
+#define ODP_ETH_LEN_MAX     1514 /**< Max frame length (excl. CRC 4 bytes) */
+#define ODP_ETH_LEN_MAX_CRC 1518 /**< Max frame length (incl. CRC 4 bytes) */
 
 /**
  * Ethernet MAC address
  */
 typedef struct ODP_PACKED {
-	uint8_t addr[ODP_ETHADDR_LEN];
+	uint8_t addr[ODP_ETHADDR_LEN]; /**< @private Address */
 } odp_ethaddr_t;
 
+/** @internal Compile time assert */
 ODP_ASSERT(sizeof(odp_ethaddr_t) == ODP_ETHADDR_LEN, ODP_ETHADDR_T__SIZE_ERROR);
 
 /**
  * Ethernet header
  */
 typedef struct ODP_PACKED {
-	odp_ethaddr_t dst;
-	odp_ethaddr_t src;
-	uint16be_t type;
+	odp_ethaddr_t dst; /**< Destination address */
+	odp_ethaddr_t src; /**< Source address */
+	uint16be_t type;   /**< Type */
 } odp_ethhdr_t;
 
+/** @internal Compile time assert */
 ODP_ASSERT(sizeof(odp_ethhdr_t) == ODP_ETHHDR_LEN, ODP_ETHHDR_T__SIZE_ERROR);
 
 /**
  * VLAN header
+ *
+ * @todo Check usage of tpid vs ethertype. Check outer VLAN TPID.
  */
 typedef struct ODP_PACKED {
-	uint16be_t tpid;
-	uint16be_t tci;
+	uint16be_t tpid;   /**< Tag protocol ID (located after ethhdr.src) */
+	uint16be_t tci;    /**< Priority / CFI / VLAN ID */
 } odp_vlanhdr_t;
 
+/** @internal Compile time assert */
 ODP_ASSERT(sizeof(odp_vlanhdr_t) == ODP_VLANHDR_LEN, ODP_VLANHDR_T__SIZE_ERROR);
 
 
diff --git a/include/helper/odp_ip.h b/include/helper/odp_ip.h
index af6d23ba..9a1d1406 100644
--- a/include/helper/odp_ip.h
+++ b/include/helper/odp_ip.h
@@ -29,29 +29,48 @@ extern "C" {
 #define ODP_IPV4HDR_LEN     20  /**< Min length of IP header (no options) */
 #define ODP_IPV4HDR_IHL_MIN  5  /**< Minimum IHL value*/
 
+/** @internal Returns IPv4 version */
 #define ODP_IPV4HDR_VER(ver_ihl) (((ver_ihl) & 0xf0) >> 4)
+
+/** @internal Returns IPv4 header length */
 #define ODP_IPV4HDR_IHL(ver_ihl) ((ver_ihl) & 0x0f)
+
+/** @internal Returns IPv4 Don't fragment */
 #define ODP_IPV4HDR_FLAGS_DONT_FRAG(frag_offset)  ((frag_offset) & 0x4000)
+
+/** @internal Returns IPv4 more fragments */
 #define ODP_IPV4HDR_FLAGS_MORE_FRAGS(frag_offset)  ((frag_offset) & 0x2000)
+
+/** @internal Returns IPv4 fragment offset */
 #define ODP_IPV4HDR_FRAG_OFFSET(frag_offset) ((frag_offset) & 0x1fff)
 
+/** @internal Returns true if IPv4 packet is a fragment */
 #define ODP_IPV4HDR_IS_FRAGMENT(frag_offset) ((frag_offset) & 0x3fff)
 
+/** IPv4 header */
 typedef struct ODP_PACKED {
-	uint8_t    ver_ihl;
-	uint8_t    tos;
-	uint16be_t tot_len;
-	uint16be_t id;
-	uint16be_t frag_offset;
-	uint8_t    ttl;
-	uint8_t    proto;
-	uint16be_t chksum;
-	uint32be_t src_addr;
-	uint32be_t dst_addr;
+	uint8_t    ver_ihl;     /**< Version / Header length */
+	uint8_t    tos;         /**< Type of service */
+	uint16be_t tot_len;     /**< Total length */
+	uint16be_t id;          /**< ID */
+	uint16be_t frag_offset; /**< Fragmentation offset */
+	uint8_t    ttl;         /**< Time to live */
+	uint8_t    proto;       /**< Protocol */
+	uint16be_t chksum;      /**< Checksum */
+	uint32be_t src_addr;    /**< Source address */
+	uint32be_t dst_addr;    /**< Destination address */
 } odp_ipv4hdr_t;
 
+/** @internal Compile time assert */
 ODP_ASSERT(sizeof(odp_ipv4hdr_t) == ODP_IPV4HDR_LEN, ODP_IPV4HDR_T__SIZE_ERROR);
 
+/**
+ * Check if IPv4 checksum is valid
+ *
+ * @param pkt  ODP packet
+ *
+ * @return 1 if checksum is valid, otherwise 0
+ */
 static inline int odp_ipv4_csum_valid(odp_packet_t pkt)
 {
 	uint16be_t res = 0;
@@ -72,7 +91,13 @@ static inline int odp_ipv4_csum_valid(odp_packet_t pkt)
 	return (res == chksum) ? 1 : 0;
 }
 
-
+/**
+ * Calculate and fill in IPv4 checksum
+ *
+ * @param pkt  ODP packet
+ *
+ * @return IPv4 checksum, or 0 on failure
+ */
 static inline uint16be_t odp_ipv4_csum_update(odp_packet_t pkt)
 {
 	uint16be_t res = 0;
@@ -90,18 +115,25 @@ static inline uint16be_t odp_ipv4_csum_update(odp_packet_t pkt)
 	return res;
 }
 
+/** IPv6 version */
 #define ODP_IPV6 6
+
+/** IPv6 header length */
 #define ODP_IPV6HDR_LEN 40
 
+/**
+ * IPv6 header
+ */
 typedef struct ODP_PACKED {
-	uint32be_t ver_tc_flow;
-	uint16be_t payload_len;
-	uint8_t    next_hdr;
-	uint8_t    hop_limit;
-	uint8_t    src_addr[16];
-	uint8_t    dst_addr[16];
+	uint32be_t ver_tc_flow;  /**< Version / Traffic class / Flow label */
+	uint16be_t payload_len;  /**< Payload length */
+	uint8_t    next_hdr;     /**< Next header */
+	uint8_t    hop_limit;    /**< Hop limit */
+	uint8_t    src_addr[16]; /**< Source address */
+	uint8_t    dst_addr[16]; /**< Destination address */
 } odp_ipv6hdr_t;
 
+/** @internal Compile time assert */
 ODP_ASSERT(sizeof(odp_ipv6hdr_t) == ODP_IPV6HDR_LEN, ODP_IPV6HDR_T__SIZE_ERROR);
 
 /* IP protocol values (IPv4:'proto' or IPv6:'next_hdr') */
diff --git a/include/helper/odp_linux.h b/include/helper/odp_linux.h
index 38a1f514..3e91ce0e 100644
--- a/include/helper/odp_linux.h
+++ b/include/helper/odp_linux.h
@@ -24,10 +24,10 @@ extern "C" {
 
 #include <pthread.h>
 
-
+/** Pthread status data */
 typedef struct {
-	pthread_t      thread;
-	pthread_attr_t attr;
+	pthread_t      thread; /**< @private Pthread */
+	pthread_attr_t attr;   /**< @private Pthread attributes */
 
 } odp_linux_pthread_t;
 
diff --git a/include/helper/odp_packet_helper.h b/include/helper/odp_packet_helper.h
index ce3ce4d1..eed866e4 100644
--- a/include/helper/odp_packet_helper.h
+++ b/include/helper/odp_packet_helper.h
@@ -39,7 +39,7 @@ static inline int odp_packet_is_valid(odp_packet_t pkt)
 /**
  * Helper: Allocate and initialize a packet buffer from a packet pool
  *
- * @param pool      Pool handle
+ * @param pool_id  Pool handle
  *
  * @note  The pool must have been created with 'buf_type=ODP_BUFFER_TYPE_PACKET'
  *
@@ -92,7 +92,7 @@ static inline size_t odp_packet_buf_size(odp_packet_t pkt)
 /**
  * Helper: Tests if packet is part of a scatter/gather list
  *
- * @param buf  Packet handle
+ * @param pkt  Packet handle
  *
  * @return 1 if belongs to a scatter list, otherwise 0
  */
diff --git a/include/helper/odp_ring.h b/include/helper/odp_ring.h
index 60feef38..ed58e912 100644
--- a/include/helper/odp_ring.h
+++ b/include/helper/odp_ring.h
@@ -124,11 +124,15 @@ enum odp_ring_queue_behavior {
  * a problem.
  */
 typedef struct odp_ring {
-	TAILQ_ENTRY(odp_ring) next;      /* Next in list. */
+	/** @private Next in list. */
+	TAILQ_ENTRY(odp_ring) next;
 
-	char name[ODP_RING_NAMESIZE];    /* Name of the ring. */
-	int flags;                       /* Flags supplied at creation. */
+	/** @private Name of the ring. */
+	char name[ODP_RING_NAMESIZE];
+	/** @private Flags supplied at creation. */
+	int flags;
 
+	/** @private Producer */
 	struct prod {
 		uint32_t watermark;      /* Maximum items */
 		uint32_t sp_enqueue;     /* True, if single producer. */
@@ -138,6 +142,7 @@ typedef struct odp_ring {
 		uint32_t tail;		/* Producer tail. */
 	} prod ODP_ALIGNED_CACHE;
 
+	/** @private Consumer */
 	struct cons {
 		uint32_t sc_dequeue;     /* True, if single consumer. */
 		uint32_t size;           /* Size of the ring. */
@@ -146,7 +151,8 @@ typedef struct odp_ring {
 		uint32_t tail;		/* Consumer tail. */
 	} cons ODP_ALIGNED_CACHE;
 
-	void *ring[0] ODP_ALIGNED_CACHE;/* Memory space of ring starts here. */
+	/** @private Memory space of ring starts here. */
+	void *ring[0] ODP_ALIGNED_CACHE;
 } odp_ring_t;
 
 
diff --git a/include/helper/odp_udp.h b/include/helper/odp_udp.h
index 2d2afbc7..738470eb 100644
--- a/include/helper/odp_udp.h
+++ b/include/helper/odp_udp.h
@@ -22,15 +22,19 @@ extern "C" {
 #include <odp_debug.h>
 #include <odp_byteorder.h>
 
+/** UDP header length */
 #define ODP_UDPHDR_LEN 8
 
+/** UDP header */
 typedef struct ODP_PACKED {
-	uint16be_t src_port; /**< Source port number */
-	uint16be_t dst_port; /**< Destination port number */
+	uint16be_t src_port; /**< Source port */
+	uint16be_t dst_port; /**< Destination port */
 	uint16be_t length;   /**< UDP datagram length in bytes (header+data) */
 	uint16be_t chksum;   /**< UDP header and data checksum (0 if not used)*/
 } odp_udphdr_t;
 
+
+/** @internal Compile time assert */
 ODP_ASSERT(sizeof(odp_udphdr_t) == ODP_UDPHDR_LEN, ODP_UDPHDR_T__SIZE_ERROR);
 
 #ifdef __cplusplus
diff --git a/include/odp_align.h b/include/odp_align.h
index 67a7cdca..ce72f01c 100644
--- a/include/odp_align.h
+++ b/include/odp_align.h
@@ -22,28 +22,45 @@ extern "C" {
 #ifdef __GNUC__
 
 /* Checkpatch complains, but cannot use __aligned(size) for this purpose. */
+
+/**
+ * Defines type/struct/variable alignment in bytes
+ */
 #define ODP_ALIGNED(x) __attribute__((__aligned__(x)))
 
+/**
+ * Defines type/struct to be packed
+ */
 #define ODP_PACKED __attribute__((__packed__))
 
+/**
+ * Returns offset of member in type
+ */
 #define ODP_OFFSETOF(type, member) __builtin_offsetof(type, member)
 
+/**
+ * Returns sizeof member
+ */
 #define ODP_FIELD_SIZEOF(type, member) sizeof(((type *)0)->member)
 
 #if defined __x86_64__ || defined __i386__
 
+/** Cache line size */
 #define ODP_CACHE_LINE_SIZE 64
 
 #elif defined __arm__
 
+/** Cache line size */
 #define ODP_CACHE_LINE_SIZE 64
 
 #elif defined __OCTEON__
 
+/** Cache line size */
 #define ODP_CACHE_LINE_SIZE 128
 
 #elif defined __powerpc__
 
+/** Cache line size */
 #define ODP_CACHE_LINE_SIZE 64
 
 #else
@@ -54,7 +71,7 @@ extern "C" {
 #error Non-gcc compatible compiler
 #endif
 
-
+/** Page size */
 #define ODP_PAGE_SIZE       4096
 
 
@@ -62,18 +79,38 @@ extern "C" {
  * Round up
  */
 
+/**
+ * @internal
+ * Round up 'x' to alignment 'align'
+ */
 #define ODP_ALIGN_ROUNDUP(x, align)\
 	((align) * (((x) + align - 1) / (align)))
 
+/**
+ * @internal
+ * Round up pointer 'x' to alignment 'align'
+ */
 #define ODP_ALIGN_ROUNDUP_PTR(x, align)\
 	((void *)ODP_ALIGN_ROUNDUP((uintptr_t)(x), (uintptr_t)(align)))
 
+/**
+ * @internal
+ * Round up 'x' to cache line size alignment
+ */
 #define ODP_CACHE_LINE_SIZE_ROUNDUP(x)\
 	ODP_ALIGN_ROUNDUP(x, ODP_CACHE_LINE_SIZE)
 
+/**
+ * @internal
+ * Round up pointer 'x' to cache line size alignment
+ */
 #define ODP_CACHE_LINE_SIZE_ROUNDUP_PTR(x)\
 	((void *)ODP_CACHE_LINE_SIZE_ROUNDUP((uintptr_t)(x)))
 
+/**
+ * @internal
+ * Round up 'x' to page size alignment
+ */
 #define ODP_PAGE_SIZE_ROUNDUP(x)\
 	ODP_ALIGN_ROUNDUP(x, ODP_PAGE_SIZE)
 
@@ -82,20 +119,39 @@ extern "C" {
  * Round down
  */
 
+/**
+ * @internal
+ * Round down 'x' to 'align' alignment, which is a power of two
+ */
 #define ODP_ALIGN_ROUNDDOWN_POWER_2(x, align)\
 	((x) & (~((align) - 1)))
 
+/**
+ * @internal
+ * Round down pointer 'x' to 'align' alignment, which is a power of two
+ */
 #define ODP_ALIGN_ROUNDDOWN_PTR_POWER_2(x, align)\
 ((void *)ODP_ALIGN_ROUNDDOWN_POWER_2((uintptr_t)(x), (uintptr_t)(align)))
 
+/**
+ * @internal
+ * Round down 'x' to cache line size alignment
+ */
 #define ODP_CACHE_LINE_SIZE_ROUNDDOWN(x)\
 	ODP_ALIGN_ROUNDDOWN_POWER_2(x, ODP_CACHE_LINE_SIZE)
 
+/**
+ * @internal
+ * Round down pointer 'x' to cache line size alignment
+ */
 #define ODP_CACHE_LINE_SIZE_ROUNDDOWN_PTR(x)\
 	((void *)ODP_CACHE_LINE_SIZE_ROUNDDOWN((uintptr_t)(x)))
 
 
+/** Defines type/struct/variable to be cache line size aligned */
 #define ODP_ALIGNED_CACHE   ODP_ALIGNED(ODP_CACHE_LINE_SIZE)
+
+/** Defines type/struct/variable to be page size aligned */
 #define ODP_ALIGNED_PAGE    ODP_ALIGNED(ODP_PAGE_SIZE)
 
 
@@ -104,12 +160,16 @@ extern "C" {
  * Check align
  */
 
-
+/**
+ * @internal
+ * Check if pointer 'x' is aligned to 'align', which is a power of two
+ */
 #define ODP_ALIGNED_CHECK_POWER_2(x, align)\
 	((((uintptr_t)(x)) & (((uintptr_t)(align))-1)) == 0)
 
-/*
- * Check value power of 2
+/**
+ * @internal
+ * Check if value is a power of two
  */
 #define ODP_VAL_IS_POWER_2(x) ((((x)-1) & (x)) == 0)
 
diff --git a/include/odp_barrier.h b/include/odp_barrier.h
index 0a1404b9..4547a260 100644
--- a/include/odp_barrier.h
+++ b/include/odp_barrier.h
@@ -27,8 +27,8 @@ extern "C" {
  * ODP execution barrier
  */
 typedef struct odp_barrier_t {
-	int              count;
-	odp_atomic_int_t bar;
+	int              count;  /**< @private Thread count */
+	odp_atomic_int_t bar;    /**< @private Barrier counter */
 } odp_barrier_t;
 
 
diff --git a/include/odp_buffer.h b/include/odp_buffer.h
index d8e47798..2d2c25aa 100644
--- a/include/odp_buffer.h
+++ b/include/odp_buffer.h
@@ -31,7 +31,7 @@ extern "C" {
  */
 typedef uint32_t odp_buffer_t;
 
-#define ODP_BUFFER_INVALID (0xffffffff)
+#define ODP_BUFFER_INVALID (0xffffffff) /**< Invalid buffer */
 
 
 /**
diff --git a/include/odp_buffer_pool.h b/include/odp_buffer_pool.h
index 15f0be43..8ac744aa 100644
--- a/include/odp_buffer_pool.h
+++ b/include/odp_buffer_pool.h
@@ -23,10 +23,13 @@ extern "C" {
 #include <odp_std_types.h>
 #include <odp_buffer.h>
 
-
+/** Maximum queue name lenght in chars */
 #define ODP_BUFFER_POOL_NAME_LEN  32
+
+/** Invalid buffer pool */
 #define ODP_BUFFER_POOL_INVALID  (0xffffffff)
 
+/** ODP buffer pool */
 typedef uint32_t odp_buffer_pool_t;
 
 
diff --git a/include/odp_byteorder.h b/include/odp_byteorder.h
index 0450946e..c573bb6a 100644
--- a/include/odp_byteorder.h
+++ b/include/odp_byteorder.h
@@ -26,9 +26,13 @@ extern "C" {
 #error BYTE_ORDER not defined!
 #endif
 
+/** Big endian byte order */
 #define ODP_BIG_ENDIAN    BIG_ENDIAN
+
+/** Little endian byte order */
 #define ODP_LITTLE_ENDIAN LITTLE_ENDIAN
 
+/** Selected byte order */
 #if BYTE_ORDER == LITTLE_ENDIAN
 #define ODP_BYTE_ORDER ODP_LITTLE_ENDIAN
 #elif BYTE_ORDER == BIG_ENDIAN
@@ -38,10 +42,14 @@ extern "C" {
 
 /* for use with type checkers such as sparse */
 #ifdef __CHECKER__
+/** @internal bitwise attribute */
 #define __odp_bitwise	__attribute__((bitwise))
+/** @internal force attribute */
 #define __odp_force     __attribute__((force))
 #else
+/** @internal bitwise attribute */
 #define __odp_bitwise
+/** @internal force attribute */
 #define __odp_force
 #endif
 
diff --git a/include/odp_compiler.h b/include/odp_compiler.h
index f4627b47..a4e6e78b 100644
--- a/include/odp_compiler.h
+++ b/include/odp_compiler.h
@@ -18,11 +18,13 @@
 extern "C" {
 #endif
 
+/** @internal GNU compiler version */
 #define GCC_VERSION (__GNUC__ * 10000 \
 			+ __GNUC_MINOR__ * 100 \
 			+ __GNUC_PATCHLEVEL__)
 
-/*
+/**
+ * @internal
  * Compiler __builtin_bswap16() is not available on all platforms
  * until GCC 4.8.0 - work around this by offering __odp_builtin_bswap16()
  * Don't use this function directly, instead see odp_byteorder.h
diff --git a/include/odp_coremask.h b/include/odp_coremask.h
index 3f537e11..1aeec3e0 100644
--- a/include/odp_coremask.h
+++ b/include/odp_coremask.h
@@ -22,7 +22,7 @@ extern "C" {
 
 #include <odp_std_types.h>
 
-
+/** @internal */
 #define ODP_COREMASK_SIZE_U64  1
 
 /**
@@ -31,7 +31,7 @@ extern "C" {
  * Don't access directly, use access functions.
  */
 typedef struct odp_coremask_t {
-	uint64_t _u64[ODP_COREMASK_SIZE_U64];
+	uint64_t _u64[ODP_COREMASK_SIZE_U64]; /**< @private Mask*/
 
 } odp_coremask_t;
 
diff --git a/include/odp_packet.h b/include/odp_packet.h
index 0b693d9b..3c7c9d09 100644
--- a/include/odp_packet.h
+++ b/include/odp_packet.h
@@ -26,7 +26,10 @@ extern "C" {
  */
 typedef uint32_t odp_packet_t;
 
+/** Invalid packet */
 #define ODP_PACKET_INVALID ODP_BUFFER_INVALID
+
+/** Invalid offset */
 #define ODP_PACKET_OFFSET_INVALID ((size_t)-1)
 
 
diff --git a/include/odp_packet_io.h b/include/odp_packet_io.h
index d4d05c7d..b760d1da 100644
--- a/include/odp_packet_io.h
+++ b/include/odp_packet_io.h
@@ -27,14 +27,16 @@ extern "C" {
 
 /** ODP packet IO handle */
 typedef uint32_t odp_pktio_t;
+
+/** Invalid packet IO handle */
 #define ODP_PKTIO_INVALID 0
 
 /**
  * Open an ODP packet IO instance
  *
- * @param dev   Packet IO device
- * @param pool  Pool to use for packet IO
- * @param param Set of parameters to pass to the arch dependent implementation
+ * @param dev    Packet IO device
+ * @param pool   Pool to use for packet IO
+ * @param params Set of parameters to pass to the arch dependent implementation
  *
  * @return ODP packet IO handle or ODP_PKTIO_INVALID on error
  */
diff --git a/include/odp_queue.h b/include/odp_queue.h
index 24ed2221..24806eb7 100644
--- a/include/odp_queue.h
+++ b/include/odp_queue.h
@@ -28,8 +28,10 @@ extern "C" {
  */
 typedef uint32_t odp_queue_t;
 
+/** Invalid queue */
 #define ODP_QUEUE_INVALID  0
 
+/** Maximum queue name lenght in chars */
 #define ODP_QUEUE_NAME_LEN 32
 
 
@@ -38,29 +40,39 @@ typedef uint32_t odp_queue_t;
  */
 typedef int odp_queue_type_t;
 
-#define ODP_QUEUE_TYPE_SCHED  0
-#define ODP_QUEUE_TYPE_POLL   1
-#define ODP_QUEUE_TYPE_PKTIN  2
-#define ODP_QUEUE_TYPE_PKTOUT 3
+#define ODP_QUEUE_TYPE_SCHED  0  /**< Scheduled queue */
+#define ODP_QUEUE_TYPE_POLL   1  /**< Not scheduled queue */
+#define ODP_QUEUE_TYPE_PKTIN  2  /**< Packet input queue */
+#define ODP_QUEUE_TYPE_PKTOUT 3  /**< Packet output queue */
 
 /**
  * ODP schedule priority
  */
 typedef int odp_schedule_prio_t;
 
+/** Highest scheduling priority */
 #define ODP_SCHED_PRIO_HIGHEST  0
+
+/** Normal scheduling priority */
 #define ODP_SCHED_PRIO_NORMAL   (ODP_CONFIG_SCHED_PRIOS / 2)
+
+/** Lowest scheduling priority */
 #define ODP_SCHED_PRIO_LOWEST   (ODP_CONFIG_SCHED_PRIOS - 1)
+
+/** Default scheduling priority */
 #define ODP_SCHED_PRIO_DEFAULT  ODP_SCHED_PRIO_NORMAL
 
+
 /**
  * ODP schedule synchronisation
  */
 typedef int odp_schedule_sync_t;
 
-#define ODP_SCHED_SYNC_NONE     0
-#define ODP_SCHED_SYNC_ATOMIC   1
-#define ODP_SCHED_SYNC_ORDERED  2
+#define ODP_SCHED_SYNC_NONE     0  /**< Queue not synchronised */
+#define ODP_SCHED_SYNC_ATOMIC   1  /**< Atomic queue */
+#define ODP_SCHED_SYNC_ORDERED  2  /**< Ordered queue */
+
+/** Default queue synchronisation */
 #define ODP_SCHED_SYNC_DEFAULT  ODP_SCHED_SYNC_ATOMIC
 
 /**
@@ -68,10 +80,18 @@ typedef int odp_schedule_sync_t;
  */
 typedef int odp_schedule_group_t;
 
+/** Group of all cores */
 #define ODP_SCHED_GROUP_ALL     0
+
+/** Default core group */
 #define ODP_SCHED_GROUP_DEFAULT ODP_SCHED_GROUP_ALL
 
+
+/**
+ * ODP Queue parameters
+ */
 typedef union odp_queue_param_t {
+	/** Scheduler parameters */
 	struct {
 		odp_schedule_prio_t  prio;
 		odp_schedule_sync_t  sync;
diff --git a/include/odp_shared_memory.h b/include/odp_shared_memory.h
index 11e1c2f3..28b650df 100644
--- a/include/odp_shared_memory.h
+++ b/include/odp_shared_memory.h
@@ -21,7 +21,7 @@ extern "C" {
 
 #include <odp_std_types.h>
 
-
+/** Maximum shared memory block name lenght in chars */
 #define ODP_SHM_NAME_LEN 32
 
 
diff --git a/include/odp_spinlock.h b/include/odp_spinlock.h
index e489663b..f25d0683 100644
--- a/include/odp_spinlock.h
+++ b/include/odp_spinlock.h
@@ -26,7 +26,7 @@ extern "C" {
  * ODP spinlock
  */
 typedef struct odp_spinlock_t {
-	volatile int lock;
+	volatile int lock;  /**< @private Lock */
 } odp_spinlock_t;
 
 
diff --git a/include/odp_sync.h b/include/odp_sync.h
index 3d347e41..e5bd0fb8 100644
--- a/include/odp_sync.h
+++ b/include/odp_sync.h
@@ -19,6 +19,12 @@ extern "C" {
 #endif
 
 
+/**
+ * Synchronise stores
+ *
+ * Ensures that all CPU store operations that precede the odp_sync_stores()
+ * call are globally visible before any store operation that follows it.
+ */
 static inline void odp_sync_stores(void)
 {
 #if defined __x86_64__ || defined __i386__
diff --git a/include/odp_ticketlock.h b/include/odp_ticketlock.h
index 9cf76dee..6277a18e 100644
--- a/include/odp_ticketlock.h
+++ b/include/odp_ticketlock.h
@@ -27,8 +27,8 @@ extern "C" {
  * ODP ticketlock
  */
 typedef struct odp_ticketlock_t {
-	odp_atomic_u32_t  next_ticket;
-	volatile uint32_t cur_ticket;
+	odp_atomic_u32_t  next_ticket; /**< @private Next ticket */
+	volatile uint32_t cur_ticket;  /**< @private Current ticket */
 } odp_ticketlock_t;
 
 
diff --git a/include/odp_timer.h b/include/odp_timer.h
index 0b6dc510..80babd1e 100644
--- a/include/odp_timer.h
+++ b/include/odp_timer.h
@@ -29,6 +29,7 @@ extern "C" {
 */
 typedef uint32_t odp_timer_t;
 
+/** Invalid timer */
 #define ODP_TIMER_INVALID 0
 
 
@@ -37,6 +38,7 @@ typedef uint32_t odp_timer_t;
 */
 typedef odp_buffer_t odp_timer_tmo_t;
 
+/** Invalid timeout */
 #define ODP_TIMER_TMO_INVALID 0
 
 
diff --git a/include/odp_version.h b/include/odp_version.h
index e9bb1541..152b3293 100644
--- a/include/odp_version.h
+++ b/include/odp_version.h
@@ -45,10 +45,13 @@ extern "C" {
 #define ODP_VERSION_API_BUG   1
 
 
-
+/** @internal Version string expand */
 #define ODP_VERSION_STR_EXPAND(x)  #x
+
+/** @internal Version to string */
 #define ODP_VERSION_TO_STR(x)      ODP_VERSION_STR_EXPAND(x)
 
+/** @internal API version string */
 #define ODP_VERSION_API_STR \
 ODP_VERSION_TO_STR(ODP_VERSION_API_MAIN) "."\
 ODP_VERSION_TO_STR(ODP_VERSION_API_SUB) "."\