doxygen style documentation started and reworked unit loader in Suite

src/loaders/Conf.cpp

@@ -1,18 +1,21 @@
 #include "Conf.h"
 
-class CONF_PLANPATH_INVALID: public std::runtime_error
-{
-public:
+/// CONF_PLANPATH_INVALID - Exception thrown when the Conf type can not load the supplied path for the Plan definition
+/// file.
+class CONF_PLANPATH_INVALID: public std::runtime_error { public:
     CONF_PLANPATH_INVALID(): std::runtime_error("conf: The supplied path for the plan definition file is invalid.") {}
 };
 
-class CONF_UNITSPATH_INVALID: public std::runtime_error
-{
-public:
+/// CONF_UNITSPATH_INVALID - Exception thrown when the Conf type can not load the supplied path for the Unit definition
+/// files.
+class CONF_UNITSPATH_INVALID: public std::runtime_error { public:
     CONF_UNITSPATH_INVALID(): std::runtime_error("conf: The supplied path for the unit definition file is invalid.") {}
 };
 
-
+/// Conf::Conf - Constructor for Conf type.  Loads the configuration for the application.
+/// TODO Expand to detect when a directory path is supplied for units_path or plan_path and import all Tasks and Units.
+///
+/// \param filename - The filename to load the configuration from.
 Conf::Conf( std::string filename ): JSON_Loader()
 {
     // load the conf file.
@@ -25,12 +28,8 @@ Conf::Conf( std::string filename ): JSON_Loader()
     if (this->get_serialized(this->units_path, "units_path", true) != 0 ) { throw CONF_UNITSPATH_INVALID(); }
 };
 
-std::string Conf::get_plan_path()
-{
-    return this->plan_path.asString();
-}
+/// Conf::get_plan_path - Retrieves the path to the Plan definition file from the application configuration file.
+std::string Conf::get_plan_path() { return this->plan_path.asString(); }
 
-std::string Conf::get_units_path()
-{
-    return this->units_path.asString();
-}
+/// Conf::get_units_path - Retrieves the path to the Unit definition file from the application configuration file.
+std::string Conf::get_units_path() { return this->units_path.asString(); }

src/loaders/JSON_Loader.cpp

@@ -2,30 +2,32 @@
 #include "helpers.h"
 #include <stdexcept>
 
-class JSON_Loader_NotReady: public std::runtime_error
-{
-public:
+/// JSON_Loader_NotReady - Exception thrown when a member function is called before data is populated.
+class JSON_Loader_NotReady: public std::runtime_error { public:
     JSON_Loader_NotReady(): std::runtime_error("JSON_Loader: Tried to access JSON without actually populating JSON.") {}
 };
 
-class JSON_Loader_FileNotFound: public std::runtime_error
-{
-public:
+/// JSON_Loader_FileNotfound - Exception thrown when JSON_Loader can not find the file it is told to parse.
+class JSON_Loader_FileNotFound: public std::runtime_error { public:
     JSON_Loader_FileNotFound(): std::runtime_error("JSON_Loader: The requested file could not be found.") {}
 };
 
-class JSON_Loader_InvalidJSON: public std::runtime_error
-{
-public:
+/// JSON_Loader_InvalidJSON - Exception thrown when JSON_Loader fails to parse the JSON provided.
+class JSON_Loader_InvalidJSON: public std::runtime_error { public:
     JSON_Loader_InvalidJSON(): std::runtime_error("JSON_Loader: The JSON provided could not be parsed.") {}
 };
 
+/// JSON_Loader::JSON_Loader - Constructor for JSON_Loader base class.  Simply inits to an unpopulated state.
 JSON_Loader::JSON_Loader()
 {
     this->populated = false;
 }
 
-// loads json from a file into a deserializable type and sets to private member json_root
+/// JSON_Loader::load_json_file - Loads JSON from a filepath into a serialized representation assigned as a local member
+/// intended to be used as a buffer for further operations by base methods and derived class methods.
+///
+/// \param filename -
+/// \param verbose
 void JSON_Loader::load_json_file( std::string filename, bool verbose )
 {
     // reads from a file into a Json::Value type.
@@ -59,11 +61,15 @@ void JSON_Loader::load_json_file( std::string filename, bool verbose )
             std::cout << "Parsed '" << filename << "' with " << this->json_root.size() << " element(s)." << std::endl;
         }
     }
-    // exit successfully and set flag that this can be used now.
+    // Flag as ready for consumption.
     this->populated = true;
 }
 
-// loads json from std::string into a serialized type and sets to private member json_root
+/// JSON_Loader::load_json_string - loads json from std::string into a json::value type and sets to protected member
+/// 'json_root'.
+///
+/// \param input - The JSON-formatted string to serialize
+/// \param verbose - Whether or not to print verbose information to STDOUT.
 void JSON_Loader::load_json_string( std::string input, bool verbose )
 {
     // reads from a string into a Json::Value type.
@@ -91,20 +97,12 @@ void JSON_Loader::load_json_string( std::string input, bool verbose )
             std::cout << input << std::endl << std::endl;
         }
     }
-    // exit successfully
+    // flag as ready for consumption
     this->populated = true;
 }
 
 
-// returns the serialized representation of json_root
-//Json::Value JSON_Loader::as_serialized()
-//{
-//    if ( ! this->populated ) { throw JSON_Loader_NotReady(); }
-//
-//    return this->json_root;
-//}
-
-// returns the string representation of json_root
+/// JSON_Loader::as_string -  returns the string representation of json_root
 std::string JSON_Loader::as_string()
 {
     if ( ! this->populated ) { throw JSON_Loader_NotReady(); }
@@ -112,10 +110,12 @@ std::string JSON_Loader::as_string()
     return this->json_root.asString();
 }
 
-// returns the serialized representation of the value of a key
-// the Jason::Value object to assign the fetched value to
-// verbosity flag
-// exit or not on failure
+/// JSON_Loader::get_serialized - assigns the serialized representation of the value of a key (json::value)
+///
+/// \param input - A reference to the json::value object to receive the new value.
+/// \param key - The JSON key name to assign the value to (the root of the json::value object by name)
+/// \param verbose - Whether or not to print verbose output to STDOUT.
+/// \return - Boolean indicator of success or failure (0|1)
 int JSON_Loader::get_serialized(Json::Value &input, std::string key, bool verbose)
 {
     // throw if the class is not ready to be used.

src/loaders/Suite.cpp

@@ -1,39 +1,51 @@
+#include <string.h>
 #include "Suite.h"
 
-Suite::Suite(): JSON_Loader()
-{
-    // empty
-};
+/// Suite::Suite() - Constructor for Suite class.  The Suite class is simply a managed container for a Unit vector.
+/// Once instantiated, all methods will require either a JSON file or string to be loaded as deserialized Unit types
+/// before being called or will simply throw an exception.
+///
+/// From the high level, a Suite contains the full definitions of all potential Units to execute defined in the Unit
+/// definition files that it is loading.  It is meant to be used in such a way that as the application iterates through
+/// the Task objects contained by the application Plan, it will iterate through the appplication's Suite, which contains
+/// the definition of all available Tasks.  In this manner, defining units and executing units are split into separate
+/// human processes to allow modularly developed profiles of test suites.  As inferred, Unit is expected to be one of
+/// the two types that are only instantiated once per application run, though it is designed to be used more than once
+/// if the implementor so desires.
+Suite::Suite(): JSON_Loader() {};
 
+/// Suite::load_units_file - Uses the json_root buffer on each run to append intact Units as they're
+/// deserialized from the provided file.
+///
+/// \param filename - The file to pull the JSON-formatted units from.
+/// \param verbose - Whether to print verbose output to STDOUT.
 void Suite::load_units_file( std::string filename, bool verbose )
 {
-    // will use json_root staging buffer on each run to append to this->units vector as valid units are found.
+    // will use json_root buffer on each run to append to this->units vector as valid units are found.
     this->load_json_file( filename, verbose );
 
+    // staging buffer
     Json::Value jbuff;
 
-    // refill the json_root buffer with a json object in the
-    if ( this->get_serialized( jbuff, "units", verbose ) != 0)
+    // fill the jbuff staging buffer with a json::value object in the supplied filename
+    if ( this->get_serialized( jbuff, "units", verbose ) == 0)
     {
         this->json_root = jbuff;
     }
 
-    // assemble the units
-
-}
-
-int Suite::load_file(std::string filename, true): JSON_Loader( filename )
+    // iterate through the json::value members that have been loaded.  append to this->units vector
+    // buffer for units to append:
+    Unit tmp_U;
+    for ( int index = 0; index < this->json_root.size(); index++ )
     {
-    Json::Value raw_units = this->get_serialized("")
-    for ( int index = 0; index < raw_units.size(); index++ )
-    {
-        this->units.push_back( Unit( raw_units[ index ] ) );
+        // assemble the unit from json_root using the built-in value operator
+        tmp_U.load_root( this->json_root[ index ] );
+        // append to this->units
+        this->units.push_back( tmp_U );
     }
-    std::cout << raw_units.size() << std::endl;
-
-    return EXIT_SUCCESS;
 }
 
+// TODO Implement
 /* Unit Suite::get_unit(std::string provided_name)
 
  * returns a unit from a unitholder object by name
@@ -62,7 +74,3 @@ int Suite::load_file(std::string filename, true): JSON_Loader( filename )
     return * returnable;
 }
 */
-
-
-
-ca

src/loaders/Suite.h

@@ -6,6 +6,9 @@
 #include "JSON_Loader.h"
 #include "Unit.h"
 
+
+
+
 class Suite: public JSON_Loader
 {
     private:

src/loaders/Unit.cpp

@@ -4,6 +4,8 @@
 #include <cstdlib>
 #include <stdexcept>
 
+/// Unit_NotPopulated - Meant to be thrown when a Unit type is not populated before being used.
+/// Signaled by use of the 'populated' boolean member of the Unit class.
 class Unit_NotPopulated: public std::runtime_error
 {
 public:
@@ -15,7 +17,7 @@ Unit::Unit() {}
 // where the serialized json is broken down into object members
 int Unit::load_root(Json::Value loader_root)
 {
-
+// this needs reworked to throw an Exception if any of the values aren't loadable.
     this->name      = loader_root.get("name", "").asString();
 
     this->target    = loader_root.get("target", "").asString();