Add documentation for remaining header files.

Doxyfile

@@ -1044,6 +1044,7 @@ RECURSIVE              = YES
 # run.
 
 EXCLUDE                = include/cJSON.h \
+                         src/cJSON.c \
                          test
 
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or

include/config.h

@@ -14,14 +14,14 @@ Each member of the @ref Config is expected to outlive the @ref Config instance
 itself.
 */
 struct Config {
-  /// The directory the `bootstrap` command was run from. Does not take
+  /// @brief The directory the `bootstrap` command was run from. Does not take
   /// ownership of this pointer.
   const char *cwd;
-  /// The root directory housing our specs. Does not take ownership of this
-  /// pointer.
-  const char *root_dir;
-  /// The name of the spec we want to bootstrap. Does not take ownership of
+  /// @brief The root directory housing our specs. Does not take ownership of
   /// this pointer.
+  const char *root_dir;
+  /// @brief The name of the spec we want to bootstrap. Does not take ownership
+  /// of this pointer.
   const char *target;
 };
 

include/evaluator.h

@@ -1,3 +1,7 @@
+/**
+@file
+@brief `spec.json` and `run.sh` evaluator.
+*/
 #ifndef _BOOTSTRAP_EVALUATOR_H
 #define _BOOTSTRAP_EVALUATOR_H
 
@@ -5,6 +9,21 @@
 #include "error.h"
 #include "validator.h"
 
+/**
+@brief Run the `run.sh` script found in the configured spec.
+
+@param config
+ A reference to the parameters describing the desired spec.
+@param fields
+ The list of prompts to have answered by the user prior to executing `run.sh`.
+ Responses are included as environment variables in the invoked subshell.
+@param error
+ The out parameter containing a possible error. Set to a null pointer if no
+ error occurs. Otherwise set to an @ref Error instance.
+@return
+ If @p error is set, returns `EXIT_FAILURE`. Otherwise returns the exit code
+ returned by `run.sh`.
+*/
 int evaluate_run_sh(
   const struct Config *const config,
   const struct DynArray *const fields,

include/parser.h

@@ -1,3 +1,7 @@
+/**
+@file
+@brief `spec.json` parser.
+*/
 #ifndef _BOOTSTRAP_PARSER_H
 #define _BOOTSTRAP_PARSER_H
 
@@ -6,10 +10,19 @@
 #include "error.h"
 
 /**
-Reads in the `spec.json` file relative to the paths of the provided @Config.
+@brief Reads in the `spec.json` file relative to the paths of the provided @ref
+Config.
 
-A spec directory does not necessarily contain a `spec.json` file. If this file
-cannot be found, the @parsed pointer is set to NULL with a success return code.
+A spec directory is not required to contain a `spec.json` file. If this file
+cannot be found, the @p parsed pointer is set to NULL and no error is returned.
+
+@param config
+ The @ref Config instance describing the `spec` location.
+@param parsed
+ The out variable a valid `cJSON` instance will be placed into, if parsing is
+ successful.
+@return
+ A null pointer if no error occurs. Otherwise an @ref Error pointer.
 */
 struct Error *parse_spec_json(
   const struct Config *const config, cJSON **parsed

include/path.h

@@ -1,8 +1,25 @@
+/**
+@file
+@brief Path-related utility functions.
+*/
 #ifndef _BOOTSTRAP_PATH_H
 #define _BOOTSTRAP_PATH_H
 
 #include <stdlib.h>
 
+/**
+@brief Concatenate the list of segments into a Unix-style path.
+
+This function assumes a forward slash path separator (i.e. `/`).
+
+@param n
+ The number of segments to join together.
+@param segments
+ The path components to join together.
+@return
+ The concatenation of the path components via `/`. The caller takes ownership
+ of this value.
+*/
 char *join_path_segments(size_t n, const char *segments[static n]);
 
 #endif /* _BOOTSTRAP_PATH_H */

include/validator.h

@@ -1,3 +1,7 @@
+/**
+@file
+@brief `spec.json` validator.
+*/
 #ifndef _BOOTSTRAP_VALIDATOR_H
 #define _BOOTSTRAP_VALIDATOR_H
 
@@ -5,18 +9,58 @@
 #include "dyn_array.h"
 #include "error.h"
 
+/**
+@brief The types of fields `bootstrap` can handle.
+*/
 enum FieldType {
   FT_STRING = 1,
 };
 
+/**
+@brief A container for relevant fields of a `cJSON`-parsed field.
+
+A @ref Field refers to the top-level key-value pairs found in the `spec.json`
+file. For instance, the fields of:
+
+```json
+{
+  "abc": {
+    "type": "STRING",
+    "prompt": "ABC"
+  },
+  "def": {
+    "type": "STRING",
+    "prompt": "DEF"
+  },
+}
+```
+
+are `abc` and `def`.
+*/
 struct Field {
+  /// @brief The type of field. Denotes what prompt should be displayed prior to
+  /// evaluation.
   enum FieldType type;
-  // OWNERSHIP: Does not take ownership.
+  /// @brief A reference to the name of the field. Does not take ownership of
+  /// this value.
   const char *key;
-  // OWNERSHIP: Does not take ownership.
+  /// @brief A reference to the supplied prompt. Does not take ownership of this
+  /// value.
   const char *prompt;
 };
 
+/**
+@brief Verify the `spec.json` file is formatted correctly.
+
+@param parsed
+ A possible null pointer to the parsed `spec.json` file. If null, this method
+ simply sets *fields to a null pointer.
+@param fields
+ The array of `Field`s defined in the top-level `spec.json` file, provided
+ validation was successful.
+@return
+ A null pointer if no error occurs. Otherwise an @ref Error pointer.
+*/
 struct Error *validate_spec_json(
   const cJSON *const parsed, struct DynArray **fields
 );