doc: add Doxygen file marker to all public headers

For existing \file markers, move them to the top of the header and tweak
the wording for consistency.

Change-Id: Icce748effe4dbe97d79a8c87d31caf0ee5797058
Signed-off-by: Daniel Verkamp <daniel.verkamp@intel.com>

include/spdk/assert.h

@@ -31,6 +31,10 @@
  *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 
+/** \file
+ * Runtime and compile-time assert macros
+ */
+
 #ifndef SPDK_ASSERT_H
 #define SPDK_ASSERT_H
 

include/spdk/barrier.h

@@ -31,6 +31,10 @@
  *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 
+/** \file
+ * Memory barriers
+ */
+
 #ifndef SPDK_BARRIER_H
 #define SPDK_BARRIER_H
 

include/spdk/file.h

@@ -31,6 +31,10 @@
  *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 
+/** \file
+ * OS filesystem utility functions
+ */
+
 #ifndef SPDK_FILE_H
 #define SPDK_FILE_H
 

include/spdk/ioat.h

@@ -32,7 +32,7 @@
  */
 
 /** \file
- * This file defines the public interface to the I/OAT DMA engine driver.
+ * I/OAT DMA engine driver public interface
  */
 
 #ifndef SPDK_IOAT_H

include/spdk/ioat_spec.h

@@ -31,6 +31,11 @@
  *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 
+/**
+ * \file
+ * I/OAT specification definitions
+ */
+
 #ifndef SPDK_IOAT_SPEC_H
 #define SPDK_IOAT_SPEC_H
 

include/spdk/mmio.h

@@ -31,6 +31,10 @@
  *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 
+/** \file
+ * Memory-mapped I/O utility functions
+ */
+
 #ifndef SPDK_MMIO_H
 #define SPDK_MMIO_H
 

include/spdk/nvme.h

@@ -31,6 +31,10 @@
  *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 
+/** \file
+ * NVMe driver public API
+ */
+
 #ifndef SPDK_NVME_H
 #define SPDK_NVME_H
 
@@ -44,10 +48,6 @@ extern "C" {
 #include "spdk/pci.h"
 #include "nvme_spec.h"
 
-/** \file
- *
- */
-
 #define SPDK_NVME_DEFAULT_RETRY_COUNT	(4)
 extern int32_t		spdk_nvme_retry_count;
 

include/spdk/nvme_intel.h

@@ -31,6 +31,14 @@
  *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 
+/**
+ * \file
+ * Intel NVMe vendor-specific definitions
+ *
+ * Reference:
+ * http://www.intel.com/content/dam/www/public/us/en/documents/product-specifications/ssd-dc-p3700-spec.pdf
+ */
+
 #ifndef SPDK_NVME_INTEL_H
 #define SPDK_NVME_INTEL_H
 
@@ -43,13 +51,6 @@ extern "C" {
 
 #include "spdk/assert.h"
 
-/**
- * \file
- *
- * reference:
- * http://www.intel.com/content/dam/www/public/us/en/documents/product-specifications/ssd-dc-p3700-spec.pdf
- */
-
 enum spdk_nvme_intel_feat {
 	SPDK_NVME_INTEL_FEAT_MAX_LBA				= 0xC1,
 	SPDK_NVME_INTEL_FEAT_NATIVE_MAX_LBA			= 0xC2,

include/spdk/nvme_spec.h

@@ -31,6 +31,11 @@
  *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 
+/**
+ * \file
+ * NVMe specification definitions
+ */
+
 #ifndef SPDK_NVME_SPEC_H
 #define SPDK_NVME_SPEC_H
 
@@ -43,11 +48,6 @@ extern "C" {
 
 #include "spdk/assert.h"
 
-/**
- * \file
- *
- */
-
 /**
  * Use to mark a command to apply to all namespaces, or to retrieve global
  *  log pages.

include/spdk/pci.h

@@ -31,6 +31,10 @@
  *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 
+/** \file
+ * PCI driver abstraction layer
+ */
+
 #ifndef SPDK_PCI_H
 #define SPDK_PCI_H
 

include/spdk/pci_ids.h

@@ -31,6 +31,10 @@
  *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 
+/** \file
+ * PCI device ID list
+ */
+
 #ifndef SPDK_PCI_IDS
 #define SPDK_PCI_IDS
 

include/spdk/string.h

@@ -31,6 +31,10 @@
  *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 
+/** \file
+ * String utility functions
+ */
+
 #ifndef SPDK_STRING_H
 #define SPDK_STRING_H
 

include/spdk/vtophys.h

@@ -31,6 +31,10 @@
  *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 
+/** \file
+ * Virtual to physical address translation
+ */
+
 #ifndef SPDK_VTOPHYS_H
 #define SPDK_VTOPHYS_H
 

lib/nvme/nvme_impl.h

@@ -31,6 +31,17 @@
  *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 
+/**
+ * \file
+ * NVMe driver integration callbacks
+ *
+ * This file describes the callback functions required to integrate
+ * the userspace NVMe driver for a specific implementation.  This
+ * implementation is specific for DPDK.  Users would
+ * revise it as necessary for their own particular environment if not
+ * using it within the DPDK framework.
+ */
+
 #ifndef __NVME_IMPL_H__
 #define __NVME_IMPL_H__
 
@@ -55,16 +66,6 @@
 #include "spdk/pci_ids.h"
 #include "spdk/nvme_spec.h"
 
-/**
- * \file
- *
- * This file describes the callback functions required to integrate
- * the userspace NVMe driver for a specific implementation.  This
- * implementation is specific for DPDK for Storage.  Users would
- * revise it as necessary for their own particular environment if not
- * using it within the DPDK for Storage framework.
- */
-
 /**
  * \page nvme_driver_integration NVMe Driver Integration
  *