Add documentation section descriptions

Add DOC: statements to the header files to have each header file
start its own section in the API documentation.

Signed-off-by: Hannes Reinecke <[email protected]>

Author: hreinecke

doc/index.rst

@@ -10,6 +10,8 @@ Welcome to libnvme's documentation!
    :maxdepth: 2
    :caption: Contents:
 
+   index
+   libnvme
 
 
 Indices and tables

doc/libnvme.rst

@@ -1,3 +1,10 @@
+.. _filters.h:
+
+**filters.h**
+
+
+libnvme directory filter
+
 .. c:function:: int nvme_namespace_filter (const struct dirent *d)
 
 
@@ -76,6 +83,13 @@
 ``struct dirent ***namespaces``
 
 
+.. _ioctl.h:
+
+**ioctl.h**
+
+
+Linux NVMe ioctl interface functions
+
 
 
 .. c:type:: struct nvme_passthru_cmd
@@ -6105,6 +6119,13 @@ The nvme command status if a response was received (see
 :c:type:`enum nvme_status_field <nvme_status_field>`) or -1 with errno set otherwise.
 
 
+.. _linux.h:
+
+**linux.h**
+
+
+linux-specific utility functions
+
 .. c:function:: int nvme_fw_download_seq (int fd, __u32 size, __u32 xfer, __u32 offset, void *buf)
 
 
@@ -6437,6 +6458,13 @@ If key generation was successful the function returns 0 or
 -1 with errno set otherwise.
 
 
+.. _log.h:
+
+**log.h**
+
+
+logging functions
+
 .. c:function:: void nvme_init_logging (nvme_root_t r, int lvl, bool log_pid, bool log_tstamp)
 
    initialize logging
@@ -6460,6 +6488,13 @@ If key generation was successful the function returns 0 or
 Sets the default logging variables for the library.
 
 
+.. _tree.h:
+
+**tree.h**
+
+
+libnvme tree object interface
+
 .. c:function:: nvme_root_t nvme_create_root (FILE *fp, int log_level)
 
    Initialize root object
@@ -8424,6 +8459,13 @@ string with the contents of **attr**
 nvme_ns_t object or NULL if not found.
 
 
+.. _types.h:
+
+**types.h**
+
+
+NVMe standard definitions
+
 .. c:function:: NVME_GET (value, name)
 
    extract field from complex value
@@ -17488,6 +17530,13 @@ See :c:type:`enum nvme_status_field <nvme_status_field>`
 ``NVME_ZNS_ZRAS_REPORT_OFFLINE``
 
 
+.. _fabrics.h:
+
+**fabrics.h**
+
+
+Fabrics-specific definitions.
+
 
 
 .. c:type:: struct nvme_fabrics_config
@@ -17872,6 +17921,13 @@ Pointer to the new controller
   Maximum length of string
 
 
+.. _util.h:
+
+**util.h**
+
+
+libnvme utility functions
+
 
 
 .. c:type:: enum nvme_connect_err

src/nvme/fabrics.h

@@ -13,6 +13,12 @@
 #include <stdint.h>
 #include "tree.h"
 
+/**
+ * DOC: fabrics.h
+ *
+ * Fabrics-specific definitions.
+ */
+
 /* default to 600 seconds of reconnect attempts before giving up */
 #define NVMF_DEF_CTRL_LOSS_TMO		600
 

src/nvme/filters.h

@@ -12,6 +12,12 @@
 #include <dirent.h>
 #include "tree.h"
 
+/**
+ * DOC: filters.h
+ *
+ * libnvme directory filter
+ */
+
 /**
  * nvme_namespace_filter() -
  * @d:

src/nvme/ioctl.h

@@ -24,6 +24,12 @@
 #ifndef _LINUX_NVME_IOCTL_H
 #define _LINUX_NVME_IOCTL_H
 
+/**
+ * DOC: ioctl.h
+ *
+ * Linux NVMe ioctl interface functions
+ */
+
 /* '0' is interpreted by the kernel to mean 'apply the default timeout' */
 #define NVME_DEFAULT_IOCTL_TIMEOUT 0
 

src/nvme/linux.h

@@ -13,6 +13,12 @@
 
 #include "types.h"
 
+/**
+ * DOC: linux.h
+ *
+ * linux-specific utility functions
+ */
+
 /**
  * nvme_fw_download_seq() -
  * @fd:     File descriptor of nvme device

src/nvme/log.h

@@ -15,6 +15,12 @@
 #  define DEFAULT_LOGLEVEL LOG_NOTICE
 #endif
 
+/**
+ * DOC: log.h
+ *
+ * logging functions
+ */
+
 /**
  * nvme_init_logging() - initialize logging
  * @r: nvme_root_t context

src/nvme/tree.h

@@ -21,6 +21,12 @@
 #include "ioctl.h"
 #include "util.h"
 
+/**
+ * DOC: tree.h
+ *
+ * libnvme tree object interface
+ */
+
 typedef struct nvme_ns *nvme_ns_t;
 typedef struct nvme_path *nvme_path_t;
 typedef struct nvme_ctrl *nvme_ctrl_t;

src/nvme/types.h

@@ -15,6 +15,12 @@
 
 #include <linux/types.h>
 
+/**
+ * DOC: types.h
+ *
+ * NVMe standard definitions
+ */
+
 /**
  * NVME_GET() - extract field from complex value
  * @value: The original value of a complex field

src/nvme/util.h

@@ -11,6 +11,12 @@
 
 #include "types.h"
 
+/**
+ * DOC: util.h
+ *
+ * libnvme utility functions
+ */
+
 /**
  * enum nvme_connect_err - nvme connect error codes
  * @ENVME_CONNECT_RESOLVE:	failed to resolve host