update C documentation so breathe can extract more docs

Author: TheAssembler1

docs/source/client_api.rst

@@ -26,6 +26,21 @@ quickly navigate to each subsection:
 .. doxygentypedef:: perr_t
    :project: PDC
 
+.. doxygentypedef:: pdc_var_type_t
+   :project: PDC
+
+.. doxygenenum:: pdc_prop_type_t
+   :project: PDC
+
+.. doxygenenum:: pdc_region_partition_t
+   :project: PDC
+
+.. doxygenenum:: pdc_lifetime_t
+   :project: PDC
+
+.. doxygenenum:: pdc_prop_type_t
+   :project: PDC
+
 .. _client_api_layer:
 
 **5.2.** PDC Layer
@@ -70,6 +85,9 @@ quickly navigate to each subsection:
 .. doxygenfunction:: PDCobj_close
    :project: PDC
 
+.. doxygenfunction:: PDCprop_obj_dup
+   :project: PDC
+
 .. _client_api_regions:
 
 **5.6.** Regions

src/api/pdc_obj/include/pdc_obj.h

@@ -31,13 +31,37 @@
 /* Public Typedefs */
 /*******************/
 typedef enum { PDC_NA = 0, PDC_READ = 1, PDC_WRITE = 2 } pdc_access_t;
+
+/**
+ * @brief Partitioning strategy for PDC regions of an object.
+ *
+ * An abstract region of an object can be partitioned in four ways.
+ *
+ * The default is PDC_REGION_STATIC.
+ */
 typedef enum {
-    PDC_OBJ_STATIC     = 0,
-    PDC_REGION_STATIC  = 1,
+    /// @brief Object static partitioning.
+    /// Input transfer requests are directly packed with a one-to-one mapping.
+    /// The target data server is determined at object create/open time.
+    PDC_OBJ_STATIC = 0,
+
+    /// @brief Region static partitioning.
+    /// Each region is equally partitioned across all data servers.
+    PDC_REGION_STATIC = 1,
+
+    /// @brief Region dynamic partitioning.
+    /// The metadata server selects the data server dynamically based on
+    /// current system load to balance region assignments.
     PDC_REGION_DYNAMIC = 2,
-    PDC_REGION_LOCAL   = 3
+
+    /// @brief Node-local region placement.
+    /// The metadata server selects a data server on the same node (or closest)
+    /// to the client transferring the request.
+    PDC_REGION_LOCAL = 3
 } pdc_region_partition_t;
+
 typedef enum { PDC_BLOCK = 0, PDC_NOBLOCK = 1 } pdc_lock_mode_t;
+
 typedef enum {
     PDC_CONSISTENCY_DEFAULT  = 0,
     PDC_CONSISTENCY_POSIX    = 1,

src/api/pdc_obj/include/pdc_prop.h

@@ -34,7 +34,7 @@
 struct pdc_obj_prop {
     pdcid_t                obj_prop_id;
     size_t                 ndim;
-    uint64_t *             dims;
+    uint64_t              *dims;
     pdc_var_type_t         type;
     pdc_region_partition_t region_partition;
     pdc_consistency_t      consistency;
@@ -43,7 +43,18 @@ struct pdc_obj_prop {
 /*******************/
 /* Public Typedefs */
 /*******************/
-typedef enum { PDC_CONT_CREATE = 0, PDC_OBJ_CREATE } pdc_prop_type_t;
+
+/**
+ * @brief Type of a PDC property
+ *
+ * Indicates what the property is used for when creating objects or containers.
+ */
+typedef enum {
+    /// @brief Property applies to container creation.
+    PDC_CONT_CREATE = 0,
+    /// @brief Property applies to object creation.
+    PDC_OBJ_CREATE
+} pdc_prop_type_t;
 
 /*********************/
 /* Public Prototypes */
@@ -98,25 +109,4 @@ struct _pdc_cont_prop *PDCcont_prop_get_info(pdcid_t prop_id);
  */
 struct pdc_obj_prop *PDCobj_prop_get_info(pdcid_t prop_id);
 
-/**
- * Send updated metadata (stored as property) to metadata server
- *
- * \param obj_id[IN]            Object ID
- * \param prop_id[IN]           Object property
- *
- * \return Non-negative on success/Negative on failure
- */
-perr_t PDCprop_update(pdcid_t obj_id, pdcid_t prop_id);
-
-/**
- * **********
- *
- * \param obj_id[IN]            Object ID
- * \param tag_name [IN]         Metadta field name
- * \param tag_value [IN]        Metadta field value
- *
- * \return Non-negative on success/Negative on failure
- */
-perr_t PDCtag_get(pdcid_t obj_id, char *tag_name, void *tag_value);
-
 #endif /* PDC_PROP_H */

src/commons/include/pdc_public.h

@@ -33,7 +33,18 @@
 /*******************/
 /* Public Typedefs */
 /*******************/
-typedef int                perr_t;
+
+/**
+ * @brief PDC error
+ *
+ * Negative indicates error success otherwise
+ */
+typedef int perr_t;
+/**
+ * @brief PDC ID
+ *
+ * 0 indicates error success otherwise
+ */
 typedef uint64_t           pdcid_t;
 typedef unsigned long long psize_t;
 typedef bool               pbool_t;
@@ -42,26 +53,66 @@ typedef int    PDC_int_t;
 typedef float  PDC_float_t;
 typedef double PDC_double_t;
 
+/**
+ * @brief PDC variable types
+ *
+ * List of all variable types:
+ *
+ * - PDC_UNKNOWN    = 0    : error
+ * - PDC_SHORT      = 1    : short types
+ * - PDC_INT        = 2    : integer types (identical to int32_t)
+ * - PDC_UINT       = 3    : unsigned integer types (identical to uint32_t)
+ * - PDC_LONG       = 4    : long types
+ * - PDC_INT8       = 5    : 8-bit integer types
+ * - PDC_UINT8      = 6    : 8-bit unsigned integer types
+ * - PDC_INT16      = 7    : 16-bit integer types
+ * - PDC_UINT16     = 8    : 16-bit unsigned integer types
+ * - PDC_INT32      = 9    : 32-bit integer types, already listed as PDC_INT
+ * - PDC_UINT32     = 10   : 32-bit unsigned integer types
+ * - PDC_INT64      = 11   : 64-bit integer types
+ * - PDC_UINT64     = 12   : 64-bit unsigned integer types
+ * - PDC_FLOAT      = 13   : floating-point types
+ * - PDC_DOUBLE     = 14   : double types
+ * - PDC_CHAR       = 15   : character types
+ * - PDC_STRING     = 16   : string types
+ * - PDC_BOOLEAN    = 17   : boolean types
+ * - PDC_VOID_PTR   = 18   : void pointer type
+ * - PDC_SIZE_T     = 19   : size_t type
+ * - PDC_BULKI      = 20   : BULKI type
+ * - PDC_BULKI_ENT  = 21   : BULKI_ENTITY type
+ * - PDC_TYPE_COUNT = 22   : number of variable types (must be last)
+ */
 typedef pdc_c_var_type_t pdc_var_type_t;
 
 // FIXME: common data structure should be defined in a group of common header files.
 typedef struct pdc_kvtag_t {
-    char *   name;
+    char    *name;
     uint32_t size;
     int8_t   type;
-    void *   value;
+    void    *value;
 } pdc_kvtag_t;
 
-typedef enum { PDC_PERSIST, PDC_TRANSIENT } pdc_lifetime_t;
+/**
+ * @brief Lifetime of a PDC container
+ *
+ * The default is PDC_PERSIST
+ */
+typedef enum {
+    /// @brief The container persists beyond the lifetime of the creating process.
+    PDC_PERSIST,
+    /// @brief The container exists only for the duration
+    /// of the creating process and is deleted when the process exits.
+    PDC_TRANSIENT
+} pdc_lifetime_t;
 
 typedef enum { PDC_SERVER_DEFAULT = 0, PDC_SERVER_PER_CLIENT = 1 } pdc_server_selection_t;
 
 typedef struct pdc_histogram_t {
     pdc_var_type_t dtype;
     int            nbin;
     double         incr;
-    double *       range;
-    uint64_t *     bin;
+    double        *range;
+    uint64_t      *bin;
 } pdc_histogram_t;
 
 #define SUCCEED 0