From cb8b16a767617954408f7a6f463423217c1a8df4 Mon Sep 17 00:00:00 2001 From: Joshua Potter Date: Sat, 25 Nov 2023 12:18:36 -0700 Subject: [PATCH] Add documentation for remaining header files. --- Doxyfile | 1 + include/config.h | 10 +++++----- include/evaluator.h | 19 ++++++++++++++++++ include/parser.h | 19 +++++++++++++++--- include/path.h | 17 ++++++++++++++++ include/validator.h | 48 +++++++++++++++++++++++++++++++++++++++++++-- 6 files changed, 104 insertions(+), 10 deletions(-) diff --git a/Doxyfile b/Doxyfile index e587d5d..41d4282 100644 --- a/Doxyfile +++ b/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 diff --git a/include/config.h b/include/config.h index 41d9ac9..0b3ba71 100644 --- a/include/config.h +++ b/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; }; diff --git a/include/evaluator.h b/include/evaluator.h index 5560cc1..0df096c 100644 --- a/include/evaluator.h +++ b/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, diff --git a/include/parser.h b/include/parser.h index 4e5fe12..ba89add 100644 --- a/include/parser.h +++ b/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 diff --git a/include/path.h b/include/path.h index c83f673..e4417fd 100644 --- a/include/path.h +++ b/include/path.h @@ -1,8 +1,25 @@ +/** +@file +@brief Path-related utility functions. +*/ #ifndef _BOOTSTRAP_PATH_H #define _BOOTSTRAP_PATH_H #include +/** +@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 */ diff --git a/include/validator.h b/include/validator.h index b976c17..754866f 100644 --- a/include/validator.h +++ b/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 );