Documentation (and stubs)

9 files changed, 178 insertions, 18 deletions

diff --git a/src/archive.c b/src/archive.c
index 9fbfae7..1e62abe 100644
--- a/src/archive.c
+++ b/src/archive.c
@@ -35,6 +35,12 @@ int tar_extract_file(const char *archive, const char* filename, const char *dest
     return status;
 }
 
+/**
+ *
+ * @param _archive
+ * @param _destination
+ * @return
+ */
 int tar_extract_archive(const char *_archive, const char *_destination) {
     Process *proc = NULL;
     int status;
diff --git a/src/checksum.c b/src/checksum.c
index d777edc..4484a6d 100644
--- a/src/checksum.c
+++ b/src/checksum.c
@@ -5,6 +5,11 @@
 #include <openssl/md5.h>
 #include <openssl/sha.h>
 
+/**
+ *
+ * @param filename
+ * @return
+ */
 char *md5sum(const char *filename) {
     size_t bytes = 0;
     unsigned char digest[MD5_DIGEST_LENGTH];
@@ -36,6 +41,11 @@ char *md5sum(const char *filename) {
     return result;
 }
 
+/**
+ *
+ * @param filename
+ * @return
+ */
 char *sha256sum(const char *filename) {
     size_t bytes = 0;
     unsigned char digest[SHA256_DIGEST_LENGTH];
diff --git a/src/config.c b/src/config.c
index 1eaed15..7b62311 100644
--- a/src/config.c
+++ b/src/config.c
@@ -8,6 +8,16 @@
  *
  * NOTE: All values are stored as strings. You need to convert non-string values yourself.
  *
+ * Example:
+ * ~~~{.c}
+ * ConfigItem **items = config_read("example.cfg");
+ * if (!items) {
+ *     // handle error
+ * }
+ * config_free(items);
+ * ~~~
+ *
+ *
  * @param filename
  * @return success=`ConfigItem` array, failure=NULL
  */
@@ -124,7 +134,19 @@ void config_free(ConfigItem **item) {
 }
 
 /**
- * If the configuration contains `key` return a pointer to that record
+ * If the `ConfigItem` array contains `key`, return a pointer to that record
+ *
+ * Example:
+ * ~~~{.c}
+ * char *nptr = NULL;
+ * ConfigItem *item = config_get(items, "a_number");
+ * if (!item) {
+ *     // handle error
+ * }
+ * int the_number = strtol(item->value, &nptr, 10);
+ * printf("%s = %d\n", item->key, the_number);
+ * ~~~
+ *
  * @param item pointer to array of config records
  * @param key search for key in config records
  * @return success=pointer to record, failure=NULL
diff --git a/src/config_global.c b/src/config_global.c
index 4184eba..0dfa6db 100644
--- a/src/config_global.c
+++ b/src/config_global.c
@@ -3,6 +3,11 @@
  */
 #include "spm.h"
 
+/**
+ * Get path to user's local configuration directory
+ * (The path will be created if it doesn't exist)
+ * @return
+ */
 char *get_user_conf_dir(void) {
     char *result = NULL;
     wordexp_t wexp;
@@ -22,6 +27,10 @@ char *get_user_conf_dir(void) {
     return result;
 }
 
+/**
+ * Get path to user's local configuration file
+ * @return
+ */
 char *get_user_config_file(void) {
     const char *filename = "spm.conf";
     char template[PATH_MAX];
@@ -42,6 +51,10 @@ char *get_user_config_file(void) {
     return strdup(template);
 }
 
+/**
+ * Determine location of temporary storage location
+ * @return
+ */
 char *get_user_tmp_dir(void) {
     char template[PATH_MAX];
     char *ucd = get_user_conf_dir();
@@ -57,6 +70,10 @@ char *get_user_tmp_dir(void) {
     return strdup(template);
 }
 
+/**
+ * Determine location of package directory
+ * @return
+ */
 char *get_user_package_dir(void) {
     char template[PATH_MAX];
     char *ucd = get_user_conf_dir();
@@ -72,6 +89,10 @@ char *get_user_package_dir(void) {
     return strdup(template);
 }
 
+/**
+ * Determine location of the package manifest
+ * @return
+ */
 char *get_package_manifest(void) {
     char template[PATH_MAX];
     char *ucd = get_user_conf_dir();
@@ -89,12 +110,14 @@ char *get_package_manifest(void) {
     free(ucd);
     return strdup(template);
 }
+
 /**
  * Check whether SPM has access to external programs it needs
  */
 void check_runtime_environment(void) {
     int bad_rt = 0;
     char *required[] = {
+            "file",
             "patchelf",
             "rsync",
             "tar",
@@ -115,6 +138,9 @@ void check_runtime_environment(void) {
     }
 }
 
+/**
+ * Populate global configuration structure
+ */
 void init_config_global(void) {
     SPM_GLOBAL.user_config_basedir = NULL;
     SPM_GLOBAL.user_config_file = NULL;
@@ -185,6 +211,9 @@ void init_config_global(void) {
     }
 }
 
+/**
+ * Free memory allocated for global configuration
+ */
 void free_global_config(void) {
     if (SPM_GLOBAL.package_dir) {
         free(SPM_GLOBAL.package_dir);
@@ -206,6 +235,9 @@ void free_global_config(void) {
     }
 }
 
+/**
+ * Display global configuration data
+ */
 void show_global_config(void) {
     printf("#---------------------------\n");
     printf("#---- SPM CONFIGURATION ----\n");
diff --git a/src/deps.c b/src/deps.c
index 84b66e1..071610d 100644
--- a/src/deps.c
+++ b/src/deps.c
@@ -3,10 +3,12 @@
  */
 #include "spm.h"
 
-int exists(const char *filename) {
-    return access(filename, F_OK);
-}
-
+/**
+ *
+ * @param deps
+ * @param name
+ * @return
+ */
 int dep_seen(Dependencies **deps, const char *name) {
     if (!deps) {
         return -1;
@@ -19,6 +21,11 @@ int dep_seen(Dependencies **deps, const char *name) {
     return 0;
 }
 
+/**
+ *
+ * @param deps
+ * @return
+ */
 int dep_init(Dependencies **deps) {
     (*deps) = (Dependencies *)calloc(1, sizeof(Dependencies));
     (*deps)->__size = 2;
@@ -30,6 +37,10 @@ int dep_init(Dependencies **deps) {
     return 0;
 }
 
+/**
+ *
+ * @param deps
+ */
 void dep_free(Dependencies **deps) {
     if ((*deps) != NULL) {
         return;
@@ -42,6 +53,12 @@ void dep_free(Dependencies **deps) {
     free((*deps));
 }
 
+/**
+ *
+ * @param deps
+ * @param _name
+ * @return
+ */
 int dep_append(Dependencies **deps, char *_name) {
     char *name = NULL;
     char *bname = NULL;
@@ -84,6 +101,12 @@ int dep_append(Dependencies **deps, char *_name) {
     return 0;
 }
 
+/**
+ *
+ * @param deps
+ * @param filename
+ * @return
+ */
 int dep_solve(Dependencies **deps, const char *filename) {
     if (!(*deps)) {
         return -1;
@@ -129,6 +152,12 @@ int dep_solve(Dependencies **deps, const char *filename) {
     return line_count;
 }
 
+/**
+ *
+ * @param deps
+ * @param _package
+ * @return
+ */
 int dep_all(Dependencies **deps, const char *_package) {
     static int next = 0;
     char *package = NULL;
@@ -178,6 +207,10 @@ int dep_all(Dependencies **deps, const char *_package) {
     return 0;
 }
 
+/**
+ *
+ * @param deps
+ */
 void dep_show(Dependencies **deps) {
     if ((*deps) == NULL) {
         return;
diff --git a/src/fs.c b/src/fs.c
index 5ea8f6b..7441573 100644
--- a/src/fs.c
+++ b/src/fs.c
@@ -3,6 +3,11 @@
  */
 #include "spm.h"
 
+/**
+ *
+ * @param _path
+ * @return
+ */
 FSTree *fstree(const char *_path) {
     FTS *parent = NULL;
     FTSENT *node = NULL;
@@ -58,10 +63,21 @@ FSTree *fstree(const char *_path) {
     return fsdata;
 }
 
+/**
+ *
+ * @param one
+ * @param two
+ * @return
+ */
 int _fstree_compare(const FTSENT **one, const FTSENT **two) {
     return (strcmp((*one)->fts_name, (*two)->fts_name));
 }
 
+/**
+ *
+ * @param _path
+ * @return
+ */
 int rmdirs(const char *_path) {
     if (access(_path, F_OK) != 0) {
         return -1;
@@ -84,6 +100,10 @@ int rmdirs(const char *_path) {
     return 0;
 }
 
+/**
+ * Free a `FSTree` structure
+ * @param fsdata
+ */
 void fstree_free(FSTree *fsdata) {
     if (fsdata != NULL) {
         if (fsdata->root != NULL) {
@@ -346,6 +366,22 @@ int mkdirs(const char *_path, mode_t mode) {
 }
 
 /**
+ * Short wrapper for `access`. Check if file exists.
+ *
+ * Example:
+ * ~~~{.c}
+ * if (exists("example.txt") != 0) {
+ *     // handle error
+ * }
+ * ~~~
+ * @param filename
+ * @return
+ */
+int exists(const char *filename) {
+    return access(filename, F_OK);
+}
+
+/**
  * Convert size in bytes to the closest human-readable unit
  *
  * NOTE: Caller is responsible for freeing memory
diff --git a/src/manifest.c b/src/manifest.c
index e527e69..672d136 100644
--- a/src/manifest.c
+++ b/src/manifest.c
@@ -6,9 +6,9 @@
 #define PACKAGE_MIN_DELIM 2
 
 /**
- *
- * @param package_dir
- * @return
+ * Generate a `Manifest` of package data
+ * @param package_dir a directory containing SPM packages
+ * @return `Manifest`
  */
 Manifest *manifest_from(const char *package_dir) {
     FSTree *fsdata = NULL;
@@ -42,6 +42,8 @@ Manifest *manifest_from(const char *package_dir) {
         }
         dep_free(&deps);
 
+        // Replace unwanted hyphens in the package name with an invalid character to prevent splitting on the wrong
+        // hyphen below
         int delims = num_chars(fsdata->files[i], '-');
         if (delims > PACKAGE_MIN_DELIM) {
             for (int t = strlen(fsdata->files[i]); t != 0; t--) {
@@ -54,10 +56,14 @@ Manifest *manifest_from(const char *package_dir) {
             }
         }
 
+        // Split the package name into parts (invalid characters are ignored)
         char **parts = split(fsdata->files[i], "-");
+
+        // Replace invalid character with a hyphen
         replace_text(parts[0], "*", "-");
         replace_text(fsdata->files[i], "*", "-");
 
+        // Populate `ManifestPackage` record
         info->packages[i]->size = get_file_size(fsdata->files[i]);
         strncpy(info->packages[i]->archive, basename(fsdata->files[i]), PACKAGE_MEMBER_SIZE);
         strncpy(info->packages[i]->name, basename(parts[0]), PACKAGE_MEMBER_SIZE);
@@ -66,13 +72,13 @@ Manifest *manifest_from(const char *package_dir) {
         strdelsuffix(info->packages[i]->revision, SPM_PACKAGE_EXTENSION);
         split_free(parts);
     }
-    //printf("\n");
+
     return info;
 }
 
 /**
- *
- * @param info
+ * Free a `Manifest` structure
+ * @param info `Manifest`
  */
 void manifest_free(Manifest *info) {
     for (int i = 0; i < info->records; i++) {
@@ -89,7 +95,7 @@ void manifest_free(Manifest *info) {
 }
 
 /**
- *
+ * Write a `Manifest` to the configuration directory
  * @param info
  * @return
  */
@@ -101,6 +107,7 @@ int manifest_write(Manifest *info) {
     FILE *fp = fopen(path, "w+");
     char *reqs = NULL;
 
+    // A little too much information (debug?)
     if (SPM_GLOBAL.verbose) {
         for (int i = 0; i < info->records; i++) {
             printf("%-20s: %s\n"
@@ -154,8 +161,8 @@ int manifest_write(Manifest *info) {
 }
 
 /**
- *
- * @return
+ * Read the package manifest stored in the configuration directory
+ * @return `Manifest` structure
  */
 Manifest *manifest_read(void) {
     const char *filename = "manifest.dat";
@@ -180,6 +187,7 @@ Manifest *manifest_read(void) {
     Manifest *info = (Manifest *)calloc(1, sizeof(Manifest));
     info->packages = (ManifestPackage **)calloc(total_records + 1, sizeof(ManifestPackage *));
 
+    // Begin parsing the manifest
     int i = 0;
     while (fgets(dptr, BUFSIZ, fp) != NULL) {
         dptr = strip(dptr);
@@ -209,10 +217,10 @@ Manifest *manifest_read(void) {
 }
 
 /**
- *
- * @param info
- * @param _package
- * @return
+ * Find a package in a `Manifest`
+ * @param info `Manifest`
+ * @param _package package name
+ * @return found=`ManifestPackage`, not found=NULL
  */
 ManifestPackage *manifest_search(Manifest *info, const char *_package) {
     char package[PATH_MAX];
diff --git a/src/relocation.c b/src/relocation.c
index 681cded..ad65f11 100644
--- a/src/relocation.c
+++ b/src/relocation.c
@@ -280,6 +280,13 @@ int prefixes_write(const char *output_file, int mode, char **prefix, const char
     return 0;
 }
 
+/**
+ * Wrapper for `reloc` program. Replace text in binary data.
+ * @param _filename
+ * @param _oldstr
+ * @param _newstr
+ * @return
+ */
 int relocate(const char *_filename, const char *_oldstr, const char *_newstr) {
     int returncode;
     Process *proc = NULL;
diff --git a/src/rpath.c b/src/rpath.c
index b7d4937..99d3403 100644
--- a/src/rpath.c
+++ b/src/rpath.c
@@ -138,6 +138,12 @@ char *rpath_generate(const char *_filename) {
     return result;
 }
 
+/**
+ * Set the RPATH of an executable
+ * @param filename
+ * @param _rpath
+ * @return
+ */
 int rpath_set(const char *filename, char *_rpath) {
     int returncode;