Add comments

2 files changed, 367 insertions, 98 deletions

diff --git a/include/deliverable.h b/include/deliverable.h
index 613d0e8..918453a 100644
--- a/include/deliverable.h
+++ b/include/deliverable.h
@@ -1,6 +1,4 @@
-//
-// Created by jhunk on 10/5/23.
-//
+/// @file deliverable.h
 
 #ifndef OHMYCAL_DELIVERABLE_H
 #define OHMYCAL_DELIVERABLE_H
@@ -22,116 +20,260 @@
 #define DELIVERY_PLATFORM_CONDA_INSTALLER 2
 #define DELIVERY_PLATFORM_RELEASE 3
 
-#define INSTALL_PKG_CONDA 1 << 1
-#define INSTALL_PKG_CONDA_DEFERRED 1 << 2
-#define INSTALL_PKG_PIP 1 << 3
-#define INSTALL_PKG_PIP_DEFERRED 1 << 4
+#define INSTALL_PKG_CONDA 1 << 1            ///< Toggle conda package installation
+#define INSTALL_PKG_CONDA_DEFERRED 1 << 2   ///< Toggle deferred conda package installation
+#define INSTALL_PKG_PIP 1 << 3              ///< Toggle pip package installation
+#define INSTALL_PKG_PIP_DEFERRED 1 << 4     ///< Toggle deferred package installation from source
 
-#define DEFER_CONDA 0
-#define DEFER_PIP 1
+#define DEFER_CONDA 0                       ///< Build conda packages
+#define DEFER_PIP 1                         ///< Build python packages
 
+/*! \struct Delivery
+ *  \brief A structure describing a full delivery object
+ */
 struct Delivery {
+    /*! \struct System
+     * \brief System information
+    */
     struct System {
         char *arch;
+        ///< System CPU architecture ident
         char platform[DELIVERY_PLATFORM_MAX][DELIVERY_PLATFORM_MAXLEN];
+        ///< System platform name
     } system;
+    /*! \struct Storage
+     * \brief Storage paths
+     */
     struct Storage {
-        char *delivery_dir;
-        char *conda_install_prefix;
-        char *conda_artifact_dir;
-        char *conda_staging_dir;
-        char *conda_staging_url;
-        char *wheel_artifact_dir;
-        char *wheel_staging_dir;
-        char *wheel_staging_url;
-        char *build_dir;
-        char *build_recipes_dir;
-        char *build_sources_dir;
-        char *build_testing_dir;
+        char *delivery_dir;             ///< Delivery artifact output directory
+        char *conda_install_prefix;     ///< Path to install Conda
+        char *conda_artifact_dir;       ///< Base path to store compiled conda packages
+        char *conda_staging_dir;        ///< Base path to copy compiled conda packages
+        char *conda_staging_url;        ///< URL to access compiled conda packages
+        char *wheel_artifact_dir;       ///< Base path to store compiled wheel packages (Unused)
+        char *wheel_staging_dir;        ///< Base path to copy compiled wheel packages (Unused)
+        char *wheel_staging_url;        ///< URL to access compiled wheel packages (Unused)
+        char *build_dir;                ///< Base path to store source code and recipes
+        char *build_recipes_dir;        ///< Path to store conda recipes
+        char *build_sources_dir;        ///< Path to store source code
+        char *build_testing_dir;        ///< Path to store test data (Unused)
     } storage;
+
+    /*! \struct Meta
+     * \brief Metadata related to the delivery
+     */
     struct Meta {
-        // delivery name
-        char *name;
-        // delivery version
-        char *version;
-        // build iteration
-        int rc;
-        // version of python to use
-        char *python;
-        // shortened python identifier
-        char *python_compact;
-        // URL to previous final configuration
-        char *based_on;
-        // hst, jwst, roman
-        char *mission;
-        // HST uses codenames
-        char *codename;
-        // is this a final release?
-        bool final;
-        // keep going, or don't
-        bool continue_on_error;
+        char *name;                ///< delivery name
+        char *version;             ///< delivery version
+        int rc;                    ///< build iteration
+        char *python;              ///< version of python to use
+        char *python_compact;      ///< shortened python identifier
+        char *based_on;            ///< URL to previous final configuration
+        char *mission;             ///< hst, jwst, roman
+        char *codename;            ///< HST uses codenames
+        bool final;                ///< is this a final release?
+        bool continue_on_error;    ///< keep going, or don't
     } meta;
 
+    /*! \struct Info
+     * \brief Release information (name & datetime)
+     */
     struct Info {
-        // The fully combined release string
-        char *release_name;
+        char *release_name;        ///< The fully combined release string
         struct tm *time_info;
-        time_t time_now;
+        time_t time_now;           ///< Time stamp for when OMC execution started
     } info;
 
+    /*! \struct Conda
+     * \brief Conda configuration
+     *
+     * This includes lists describing packages to be delivered
+     */
     struct Conda {
-        char *installer_baseurl;
-        char *installer_name;
-        char *installer_version;
-        char *installer_platform;
-        char *installer_arch;
-        char *tool_version;
-        char *tool_build_version;
-        // packages to install
-        struct StrList *conda_packages;
-        // conda recipes to be built
-        struct StrList *conda_packages_defer;
-        // packages to install
-        struct StrList *pip_packages;
-        // packages to be built
-        struct StrList *pip_packages_defer;
+        char *installer_baseurl;                ///< URL describing where Conda will be downloaded from
+        char *installer_name;                   ///< Name of installer (Miniconda3, Miniforge3, etc)
+        char *installer_version;                ///< Version of installer
+        char *installer_platform;               ///< Platform/OS target of installer
+        char *installer_arch;                   ///< CPU architecture target of installer
+        char *tool_version;                     ///< Installed version of conda
+        char *tool_build_version;               ///< Installed version of "build" package
+        struct StrList *conda_packages;         ///< Conda packages to deliver
+        struct StrList *conda_packages_defer;   ///< Conda recipes to be built for delivery
+        struct StrList *pip_packages;           ///< Python packages to install (pip)
+        struct StrList *pip_packages_defer;     ///< Python packages to be built for delivery
     } conda;
 
-    // global runtime variables
+    /*! \struct Runtime
+     *  \brief Global runtime variables
+     */
     struct Runtime {
-        RuntimeEnv *environ;
+        RuntimeEnv *environ;        ///< Environment variables
     } runtime;
 
+    /*! \struct Test
+     * \brief Test information
+     */
     struct Test {
-        char *name;
-        char *version;
-        char *repository;
-        char *script;
-        char *build_recipe;
-        // test-specific runtime variables
-        struct Runtime runtime;
-    } tests[1000];
+        char *name;                 ///< Name of package
+        char *version;              ///< Version of package
+        char *repository;           ///< Git repository of package
+        char *script;               ///< Commands to execute
+        char *build_recipe;         ///< Conda recipe to build (optional)
+        struct Runtime runtime;     ///< Environment variables specific to the test context
+    } tests[1000]; ///< An array of tests
 };
 
+/**
+ * Initializes a Deliver structure
+ * @param ctx pointer to Delivery context
+ * @param ini pointer to INIFILE describing a delivery
+ * @param cfg pointer to INIFILE describing extra configuration data
+ * @return `0` on success
+ * @return Non-zero on error
+ */
 int delivery_init(struct Delivery *ctx, struct INIFILE *ini, struct INIFILE *cfg);
+
+/**
+ * Free memory allocated by delivery_init()
+ * @param ctx pointer to Delivery context
+ */
 void delivery_free(struct Delivery *ctx);
+
+/**
+ * Print Delivery metadata
+ * @param ctx pointer to Delivery context
+ */
 void delivery_meta_show(struct Delivery *ctx);
+
+/**
+ * Print Delivery conda configuration
+ * @param ctx pointer to Delivery context
+ */
 void delivery_conda_show(struct Delivery *ctx);
+
+/**
+ * Print Delivery tests
+ * @param ctx pointer to Delivery context
+ */
 void delivery_tests_show(struct Delivery *ctx);
+
+/**
+ * Build Conda recipes associated with the Delivery
+ * @param ctx pointer to Delivery context
+ * @return 0 on success
+ * @return Non-zero on error
+ */
 int delivery_build_recipes(struct Delivery *ctx);
+
+/**
+ * Produce a list of wheels built for the Delivery (Unused)
+ * @param ctx pointer to Delivery context
+ * @return pointer to StrList
+ * @return NULL on error
+ */
 struct StrList *delivery_build_wheels(struct Delivery *ctx);
+
+/**
+ * Copy wheel packages to artifact storage
+ * @param ctx pointer to Delivery context
+ * @return 0 on success
+ * @return Non-zero on error
+ */
 int delivery_index_wheel_artifacts(struct Delivery *ctx);
+
+/**
+ * Generate a header block that is applied to delivery artifacts
+ * @param ctx pointer to Delivery context
+ * @return header on success
+ * @return NULL on error
+ */
 char *delivery_get_spec_header(struct Delivery *ctx);
+
+/**
+ * Finalizes a delivery artifact for distribution
+ * @param ctx poitner to Delivery context
+ * @param filename path to delivery artifact (Conda YAML file)
+ */
 void delivery_rewrite_spec(struct Delivery *ctx, char *filename);
+
+/**
+ * Copy compiled wheels to artifact storage
+ * @param ctx pointer to Delivery context
+ * @return 0 on success
+ * @return Non-zero on error
+ */
 int delivery_copy_wheel_artifacts(struct Delivery *ctx);
+
+/**
+ * Copy built Conda packages to artifact storage
+ * @param ctx poitner to Delivery context
+ * @return 0 on success
+ * @return Non-zero on error
+ */
 int delivery_copy_conda_artifacts(struct Delivery *ctx);
+
+/**
+ * Retrieve Conda installer
+ * @param installer_url URL to installation script
+ */
 void delivery_get_installer(char *installer_url);
+
+/**
+ * Generate URL based on Delivery context
+ * @param delivery pointer to Delivery context
+ * @param result pointer to char
+ * @return in result
+ */
 void delivery_get_installer_url(struct Delivery *delivery, char *result);
+
+/**
+ * Install packages based on Delivery context
+ * @param ctx pointer to Delivery context
+ * @param conda_install_dir path to install Conda
+ * @param env_name name of Conda environment to create
+ * @param type INSTALL_PKG_CONDA
+ * @param type INSTALL_PKG_CONDA_DEFERRED
+ * @param type INSTALL_PKG_PIP
+ * @param type INSTALL_PKG_PIP_DEFERRED
+ * @param manifest pointer to array of StrList (package list(s))
+ */
 void delivery_install_packages(struct Delivery *ctx, char *conda_install_dir, char *env_name, int type, struct StrList *manifest[]);
+
+/**
+ * Update "conda index" on Conda artifact storage
+ * @param ctx pointer to Delivery context
+ * @return 0 on success
+ * @return Non-zero on error
+ */
 int delivery_index_conda_artifacts(struct Delivery *ctx);
+
+/**
+ * Execute Delivery test array
+ * @param ctx pointer to Delivery context
+ */
 void delivery_tests_run(struct Delivery *ctx);
+
+/**
+ * Determine which packages are to be installed directly from conda or pip,
+ * and which packages need to be built locally
+ * @param ctx pointer to Delivery context
+ * @param type DEFER_CONDA (filter conda packages)
+ * @param type DEFER_PIP (filter python packages)
+ */
 void delivery_defer_packages(struct Delivery *ctx, int type);
+
+/**
+ * Configure and activate a Conda installation based on Delivery context
+ * @param ctx pointer to Delivery context
+ * @param conda_install_dir path to Conda installation
+ */
 void delivery_conda_enable(struct Delivery *ctx, char *conda_install_dir);
+
+/**
+ * Install Conda
+ * @param install_script path to Conda installation script
+ * @param conda_install_dir path to install Conda
+ */
 void delivery_install_conda(char *install_script, char *conda_install_dir);
 
 #endif //OHMYCAL_DELIVERABLE_H
diff --git a/include/ini.h b/include/ini.h
index 06004e3..f16142c 100644
--- a/include/ini.h
+++ b/include/ini.h
@@ -1,54 +1,181 @@
+/// @file ini.h
+
 #ifndef OHMYCAL_INI_H
 #define OHMYCAL_INI_H
 #include <stddef.h>
 #include <stdbool.h>
 
-#define INIVAL_TYPE_INT 1
-#define INIVAL_TYPE_UINT 2
-#define INIVAL_TYPE_LONG 3
-#define INIVAL_TYPE_ULONG 4
-#define INIVAL_TYPE_LLONG 5
-#define INIVAL_TYPE_ULLONG 6
-#define INIVAL_TYPE_DOUBLE 7
-#define INIVAL_TYPE_FLOAT 8
-#define INIVAL_TYPE_STR 9
-#define INIVAL_TYPE_STR_ARRAY 10
-#define INIVAL_TYPE_BOOL 11
+#define INIVAL_TYPE_INT 1           ///< Integer
+#define INIVAL_TYPE_UINT 2          ///< Unsigned integer
+#define INIVAL_TYPE_LONG 3          ///< Long integer
+#define INIVAL_TYPE_ULONG 4         ///< Unsigned long integer
+#define INIVAL_TYPE_LLONG 5         ///< Long long integer
+#define INIVAL_TYPE_ULLONG 6        ///< Unsigned long long integer
+#define INIVAL_TYPE_DOUBLE 7        ///< Double precision float
+#define INIVAL_TYPE_FLOAT 8         ///< Single precision float
+#define INIVAL_TYPE_STR 9           ///< String
+#define INIVAL_TYPE_STR_ARRAY 10    ///< String Array
+#define INIVAL_TYPE_BOOL 11         ///< Boolean
 
 #define INIVAL_TO_LIST 1 << 1
 
+/*! \union INIVal
+ * \brief Consolidation possible value types
+ */
 union INIVal {
-    int as_int;
-    unsigned as_uint;
-    long as_long;
-    unsigned long as_ulong;
-    long long as_llong;
-    unsigned long long as_ullong;
-    double as_double;
-    float as_float;
-    char *as_char_p;
-    char **as_char_array_p;
-    bool as_bool;
+    int as_int;                      ///< Integer
+    unsigned as_uint;                ///< Unsigned integer
+    long as_long;                    ///< Long integer
+    unsigned long as_ulong;          ///< Unsigned long integer
+    long long as_llong;              ///< Long long integer
+    unsigned long long as_ullong;    ///< Unsigned long long integer
+    double as_double;                ///< Double precision float
+    float as_float;                  ///< Single precision float
+    char *as_char_p;                 ///< String
+    char **as_char_array_p;          ///< String Array
+    bool as_bool;                    ///< Boolean
 };
 
 
+/*! \struct INIData
+ * \brief A structure to describe an INI data record
+ */
 struct INIData {
-    char *key;
-    char *value;
+    char *key;                       ///< INI variable name
+    char *value;                     ///< INI variable value
 };
+
+/*! \struct INISection
+ * \brief A structure to describe an INI section
+ */
 struct INISection {
-    size_t data_count;
-    char *key;
-    struct INIData **data;
+    size_t data_count;               ///< Total INIData records
+    char *key;                       ///< INI section name
+    struct INIData **data;           ///< Array of INIData records
 };
+
+/*! \struct INIFILE
+ * \brief A structure to describe an INI configuration file
+ */
 struct INIFILE {
-    size_t section_count;
-    struct INISection **section;
+    size_t section_count;            ///< Total INISection records
+    struct INISection **section;     ///< Array of INISection records
 };
 
+/**
+ * Open and parse and INI configuration file
+ *
+ * ~~~.c
+ * #include "ini.h"
+ * int main(int argc, char *argv[]) {
+ *     const char *filename = "example.ini"
+ *     struct INIFILE *ini;
+ *     ini = ini_open(filename);
+ *     if (!ini) {
+ *         perror(filename);
+ *         exit(1);
+ *     }
+ * }
+ * ~~~
+ *
+ * @param filename path to INI file
+ * @return pointer to INIFILE
+ */
 struct INIFILE *ini_open(const char *filename);
+
+/**
+ * Retrieve all data records in an INI section
+ *
+ * `example.ini`
+ * ~~~.ini
+ * [example]
+ * key_1 = a string
+ * key_2 = 100
+ * ~~~
+ *
+ * `example.c`
+ * ~~~.c
+ * #include "ini.h"
+ * int main(int argc, char *argv[]) {
+ *     const char *filename = "example.ini"
+ *     struct INIData *data;
+ *     struct INIFILE *ini;
+ *     ini = ini_open(filename);
+ *     if (!ini) {
+ *         perror(filename);
+ *         exit(1);
+ *     }
+ *     // Read all records in "example" section
+ *     for (size_t i = 0; ((data = ini_getall(&ini, "example") != NULL); i++) {
+ *         printf("key=%s, value=%s\n", data->key, data->value);
+ *     }
+ * }
+ * ~~~
+ *
+ * @param ini pointer to INIFILE
+ * @param section_name to read
+ * @return pointer to INIData
+ */
 struct INIData *ini_getall(struct INIFILE *ini, char *section_name);
+
+/**
+ * Retrieve a single record from a section key
+ *
+ * `example.ini`
+ * ~~~.ini
+ * [example]
+ * key_1 = a string
+ * key_2 = 100
+ * ~~~
+ *
+ * `example.c`
+ * ~~~.c
+ * #include "ini.h"
+ * int main(int argc, char *argv[]) {
+ *     const char *filename = "example.ini"
+ *     union INIVal *data;
+ *     struct INIFILE *ini;
+ *     ini = ini_open(filename);
+ *     if (!ini) {
+ *         perror(filename);
+ *         exit(1);
+ *     }
+ *     data = ini_getval(&ini, "example", "key_1", INIVAL_TYPE_STR);
+ *     puts(data.as_char_p);
+ *     data = ini_getval(&ini, "example", "key_2", INIVAL_TYPE_INT);
+ *     printf("%d\n", data.as_int);
+ * }
+ * ~~~
+ *
+ * @param ini pointer to INIFILE
+ * @param section_name to read
+ * @param key to return
+ * @param type INIVAL_TYPE_INT
+ * @param type INIVAL_TYPE_UINT
+ * @param type INIVAL_TYPE_LONG
+ * @param type INIVAL_TYPE_ULONG
+ * @param type INIVAL_TYPE_LLONG
+ * @param type INIVAL_TYPE_ULLONG
+ * @param type INIVAL_TYPE_DOUBLE
+ * @param type INIVAL_TYPE_FLOAT
+ * @param type INIVAL_TYPE_STR
+ * @param type INIVAL_TYPE_STR_ARRAY
+ * @param type INIVAL_TYPE_BOOL
+ * @param result pointer to INIVal
+ * @return 0 on success
+ * @return Non-zero on error
+ */
 int ini_getval(struct INIFILE *ini, char *section_name, char *key, int type, union INIVal *result);
+
+/**
+ * Print INIFILE sections and data
+ * @param ini pointer to INIFILE
+ */
 void ini_show(struct INIFILE *ini);
+
+/**
+ * Free memory allocated by ini_open()
+ * @param ini
+ */
 void ini_free(struct INIFILE **ini);
 #endif //OHMYCAL_INI_H