Add documentation (H5FD) (#4269)

src/H5FDdevelop.h

@@ -25,7 +25,9 @@
 /* Public Macros */
 /*****************/
 
-/* H5FD_class_t struct version */
+/**
+ * Version of the file driver struct, H5FD_class_t
+ */
 #define H5FD_CLASS_VERSION 0x01 /* File driver struct version */
 
 /* Map "fractal heap" header blocks to 'ohdr' type file memory, since its
@@ -43,70 +45,92 @@
  *
  *      -QAK
  */
-#define H5FD_MEM_FHEAP_HDR      H5FD_MEM_OHDR
-#define H5FD_MEM_FHEAP_IBLOCK   H5FD_MEM_OHDR
-#define H5FD_MEM_FHEAP_DBLOCK   H5FD_MEM_LHEAP
+
+/**
+ * Fractal heap header block; it is mapped to 'ohdr' type file memory to
+ * benefit from their similarity.
+ */
+#define H5FD_MEM_FHEAP_HDR H5FD_MEM_OHDR
+/**
+ * Fractal heap indirect block; it is mapped to 'ohdr' type file memory
+ * because the indirect blocks are similar to fractal heap header blocks.
+ */
+#define H5FD_MEM_FHEAP_IBLOCK H5FD_MEM_OHDR
+/**
+ * Fractal heap direct block; it is mapped to 'lheap' type file memory,
+ * because the fractal heap direct blocks will be replacing local heaps.
+ */
+#define H5FD_MEM_FHEAP_DBLOCK H5FD_MEM_LHEAP
+/**
+ * Fractal heap 'huge' object; it is mapped to 'draw' type file memory because
+ * the fractal heap 'huge' objects represent large objects that are directly
+ * stored in the file.
+ */
 #define H5FD_MEM_FHEAP_HUGE_OBJ H5FD_MEM_DRAW
 
-/* Map "free space" header blocks to 'ohdr' type file memory, since its
- * a fair amount of work to add a new kind of file memory and they are similar
- * enough to object headers and probably too minor to deserve their own type.
- *
- * Map "free space" serialized sections to 'lheap' type file memory, since they
- * are similar enough to local heap info.
- *
- *      -QAK
+/**
+ * Free space header blocks; it is mapped to 'ohdr' type file memory to
+ * benefit from their similarity.
+ */
+#define H5FD_MEM_FSPACE_HDR H5FD_MEM_OHDR
+/**
+ * Free space serialized section; it is mapped to 'lheap' type file memory
+ * because it is similar enough to local heap info.
  */
-#define H5FD_MEM_FSPACE_HDR   H5FD_MEM_OHDR
 #define H5FD_MEM_FSPACE_SINFO H5FD_MEM_LHEAP
 
-/* Map "shared object header message" master table to 'ohdr' type file memory,
- * since its a fair amount of work to add a new kind of file memory and they are
- * similar enough to object headers and probably too minor to deserve their own
- * type.
- *
- * Map "shared object header message" indices to 'btree' type file memory,
- * since they are similar enough to B-tree nodes.
- *
- *      -QAK
+/**
+ * Shared object header message master table; it is mapped to 'ohdr' type file
+ * memory to benefit from their similarity.
  */
 #define H5FD_MEM_SOHM_TABLE H5FD_MEM_OHDR
+/**
+ * Shared object header message index; it is mapped to 'btree' type file memory
+ * because the indices are similar enough to B-tree nodes.
+ */
 #define H5FD_MEM_SOHM_INDEX H5FD_MEM_BTREE
-
-/* Map "extensible array" header blocks to 'ohdr' type file memory, since its
- * a fair amount of work to add a new kind of file memory and they are similar
- * enough to object headers and probably too minor to deserve their own type.
- *
- * Map "extensible array" index blocks to 'ohdr' type file memory, since they
- * are similar to extensible array header blocks.
- *
- * Map "extensible array" super blocks to 'btree' type file memory, since they
- * are similar enough to B-tree nodes.
- *
- * Map "extensible array" data blocks & pages to 'lheap' type file memory, since
- * they are similar enough to local heap info.
- *
- *      -QAK
+/**
+ * Extensible array header block; it is mapped to 'ohdr' type file memory to
+ * benefit from their similarity.
+ */
+#define H5FD_MEM_EARRAY_HDR H5FD_MEM_OHDR
+/**
+ * Extensible array index block; it is mapped to 'ohdr' type file memory because
+ * these index blocks are similar to extensible array header blocks.
+ */
+#define H5FD_MEM_EARRAY_IBLOCK H5FD_MEM_OHDR
+/**
+ * Extensible array super block; it is mappend to 'btree' type file memory
+ * because the indices are similar enough to B-tree nodes.
+ */
+#define H5FD_MEM_EARRAY_SBLOCK H5FD_MEM_BTREE
+/**
+ * Extensible array data block; it is mapped to 'lheap' type file memory
+ * because it is similar enough to local heap info.
+ */
+#define H5FD_MEM_EARRAY_DBLOCK H5FD_MEM_LHEAP
+/**
+ * Extensible array data block & page; it is mapped to 'lheap' type file memory
+ * because it is similar enough to local heap info.
  */
-#define H5FD_MEM_EARRAY_HDR       H5FD_MEM_OHDR
-#define H5FD_MEM_EARRAY_IBLOCK    H5FD_MEM_OHDR
-#define H5FD_MEM_EARRAY_SBLOCK    H5FD_MEM_BTREE
-#define H5FD_MEM_EARRAY_DBLOCK    H5FD_MEM_LHEAP
 #define H5FD_MEM_EARRAY_DBLK_PAGE H5FD_MEM_LHEAP
-
-/* Map "fixed array" header blocks to 'ohdr' type file memory, since its
- * a fair amount of work to add a new kind of file memory and they are similar
- * enough to object headers and probably too minor to deserve their own type.
- *
- * Map "fixed array" data blocks & pages to 'lheap' type file memory, since
- * they are similar enough to local heap info.
- *
+/**
+ * Fixed array header block; it is mapped to 'ohdr' type file memory to
+ * benefit their similarity.
+ */
+#define H5FD_MEM_FARRAY_HDR H5FD_MEM_OHDR
+/**
+ * Fixed array data block; it is mapped to 'lheap' type file memory
+ * because it is similar enough to local heap info.
+ */
+#define H5FD_MEM_FARRAY_DBLOCK H5FD_MEM_LHEAP
+/**
+ * Fixed array data block & page; it is mapped to 'lheap' type file memory
+ * because it is similar enough to local heap info.
  */
-#define H5FD_MEM_FARRAY_HDR       H5FD_MEM_OHDR
-#define H5FD_MEM_FARRAY_DBLOCK    H5FD_MEM_LHEAP
 #define H5FD_MEM_FARRAY_DBLK_PAGE H5FD_MEM_LHEAP
 
-/*
+/**
  * A free-list map which maps all types of allocation requests to a single
  * free list.  This is useful for drivers that don't really care about
  * keeping different requests segregated in the underlying file and which
@@ -124,7 +148,7 @@
             H5FD_MEM_SUPER  /*ohdr*/                                                                         \
     }
 
-/*
+/**
  * A free-list map which segregates requests into `raw' or `meta' data
  * pools.
  */
@@ -139,7 +163,7 @@
             H5FD_MEM_SUPER  /*ohdr*/                                                                         \
     }
 
-/*
+/**
  * The default free list map which causes each request type to use it's own
  * free-list.
  */
@@ -161,80 +185,163 @@
 /* Forward declaration */
 typedef struct H5FD_t H5FD_t;
 
-/* Class information for each file driver */
+/**
+ * Class information for each file driver
+ */
 typedef struct H5FD_class_t {
-    unsigned           version; /**< File driver class struct version number */
+    unsigned version;
+    /**< File driver class struct version number */
+
     H5FD_class_value_t value;
-    const char        *name;
-    haddr_t            maxaddr;
+    /**< File driver identifier */
+
+    const char *name;
+    /**< File driver name, must be unique */
+
+    haddr_t maxaddr;
+    /**< Maximum address for file */
+
     H5F_close_degree_t fc_degree;
+    /**< File close behavior degree */
+
     herr_t (*terminate)(void);
+    /**< Shutdowns this driver */
+
     hsize_t (*sb_size)(H5FD_t *file);
+    /**< Gets the size of the private information to be stored in the superblock */
+
     herr_t (*sb_encode)(H5FD_t *file, char *name /*out*/, unsigned char *p /*out*/);
+    /**< Encodes driver information from the superblock */
+
     herr_t (*sb_decode)(H5FD_t *f, const char *name, const unsigned char *p);
-    size_t fapl_size;
+    /**< Decodes the superblock information for this driver */
+
+    size_t fapl_size; /**< Size of driver-specific file access properties */
     void *(*fapl_get)(H5FD_t *file);
+    /**< Returns the file access property list */
+
     void *(*fapl_copy)(const void *fapl);
+    /**< Copies the file access property list */
+
     herr_t (*fapl_free)(void *fapl);
+    /**< Frees the driver-specific file access property list */
+
     size_t dxpl_size;
+    /**< Size of the transfer property list */
+
     void *(*dxpl_copy)(const void *dxpl);
+    /**< Copies the transfer property list */
+
     herr_t (*dxpl_free)(void *dxpl);
+    /**< Frees the transfer property list */
+
     H5FD_t *(*open)(const char *name, unsigned flags, hid_t fapl, haddr_t maxaddr);
+    /**< Create or open an HDF5 file of this driver */
+
     herr_t (*close)(H5FD_t *file);
+    /**< Close an HDF5 file of this driver */
+
     int (*cmp)(const H5FD_t *f1, const H5FD_t *f2);
+    /**< Compares two files belonging to this driver */
+
     herr_t (*query)(const H5FD_t *f1, unsigned long *flags);
+    /**< Sets the flags that this driver is capable of supporting */
+
     herr_t (*get_type_map)(const H5FD_t *file, H5FD_mem_t *type_map);
+    /**< Retrieves the memory type mapping for this file */
+
     haddr_t (*alloc)(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, hsize_t size);
+    /**< Allocates file memory */
+
     herr_t (*free)(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, haddr_t addr, hsize_t size);
+    /**< Frees the resources for this driver */
+
     haddr_t (*get_eoa)(const H5FD_t *file, H5FD_mem_t type);
+    /**< Gets the address of first byte past the addressed space */
+
     herr_t (*set_eoa)(H5FD_t *file, H5FD_mem_t type, haddr_t addr);
+    /**< Sets the end-of-address marker for the file */
+
     haddr_t (*get_eof)(const H5FD_t *file, H5FD_mem_t type);
+    /**< Gets the address of first byte past the file-end */
+
     herr_t (*get_handle)(H5FD_t *file, hid_t fapl, void **file_handle);
+    /**< Returns the file handle of this file driver */
+
     herr_t (*read)(H5FD_t *file, H5FD_mem_t type, hid_t dxpl, haddr_t addr, size_t size, void *buffer);
+    /**< Reads the specified number of bytes of data from the file beginning at the specified
+     * address into the provided buffer, according to the specified data transfer properties  */
+
     herr_t (*write)(H5FD_t *file, H5FD_mem_t type, hid_t dxpl, haddr_t addr, size_t size, const void *buffer);
+    /**< Writes the specified number of bytes of data to the file beginning at the specified
+     * address from the provided buffer, according to the specified data transfer properties  */
+
     herr_t (*read_vector)(H5FD_t *file, hid_t dxpl, uint32_t count, H5FD_mem_t types[], haddr_t addrs[],
                           size_t sizes[], void *bufs[]);
+    /**< Reads the specified length of data from the file into the provided array */
+
     herr_t (*write_vector)(H5FD_t *file, hid_t dxpl, uint32_t count, H5FD_mem_t types[], haddr_t addrs[],
                            size_t sizes[], const void *bufs[]);
+    /**< Writes the specified length of data in the provided array to the file at the specified offsets */
+
     herr_t (*read_selection)(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, size_t count, hid_t mem_spaces[],
                              hid_t file_spaces[], haddr_t offsets[], size_t element_sizes[],
                              void *bufs[] /*out*/);
+    /**< */
+
     herr_t (*write_selection)(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, size_t count, hid_t mem_spaces[],
                               hid_t file_spaces[], haddr_t offsets[], size_t element_sizes[],
                               const void *bufs[] /*in*/);
+    /**< */
+
     herr_t (*flush)(H5FD_t *file, hid_t dxpl_id, hbool_t closing);
+    /**< Flushes all data to disk */
+
     herr_t (*truncate)(H5FD_t *file, hid_t dxpl_id, hbool_t closing);
+    /**< Truncates a file */
+
     herr_t (*lock)(H5FD_t *file, hbool_t rw);
+    /**< Places an advisory lock on a file */
+
     herr_t (*unlock)(H5FD_t *file);
+    /**< Removes the existing lock on a file */
+
     herr_t (*del)(const char *name, hid_t fapl);
+    /**< Deletes a file */
+
     herr_t (*ctl)(H5FD_t *file, uint64_t op_code, uint64_t flags, const void *input, void **output);
+    /**< Performs a CTL operation */
+
     H5FD_mem_t fl_map[H5FD_MEM_NTYPES];
+    /**< Free-list map */
 } H5FD_class_t;
 
-/* A free list is a singly-linked list of address/size pairs. */
+/**
+ * A free list is a singly-linked list of address/size pairs.
+ */
 typedef struct H5FD_free_t {
     haddr_t             addr;
     hsize_t             size;
     struct H5FD_free_t *next;
 } H5FD_free_t;
 
-/*
+/**
  * The main datatype for each driver. Public fields common to all drivers
  * are declared here and the driver appends private fields in memory.
  */
 struct H5FD_t {
-    hid_t               driver_id;     /*driver ID for this file   */
-    const H5FD_class_t *cls;           /*constant class info       */
-    unsigned long       fileno;        /* File 'serial' number     */
-    unsigned            access_flags;  /* File access flags (from create or open) */
-    unsigned long       feature_flags; /* VFL Driver feature Flags */
-    haddr_t             maxaddr;       /* For this file, overrides class */
-    haddr_t             base_addr;     /* Base address for HDF5 data w/in file */
+    hid_t               driver_id;     /**< Driver ID for this file   */
+    const H5FD_class_t *cls;           /**< Constant class info       */
+    unsigned long       fileno;        /**< File 'serial' number     */
+    unsigned            access_flags;  /**< File access flags (from create or open) */
+    unsigned long       feature_flags; /**< VFL Driver feature Flags */
+    haddr_t             maxaddr;       /**< For this file, overrides class */
+    haddr_t             base_addr;     /**< Base address for HDF5 data w/in file */
 
     /* Space allocation management fields */
-    hsize_t threshold;  /* Threshold for alignment  */
-    hsize_t alignment;  /* Allocation alignment     */
-    hbool_t paged_aggr; /* Paged aggregation for file space is enabled or not */
+    hsize_t threshold;  /**< Threshold for alignment  */
+    hsize_t alignment;  /**< Allocation alignment     */
+    hbool_t paged_aggr; /**< Paged aggregation for file space is enabled or not */
 };
 
 /* VFD initialization function */