REFORM-1002 Create documentation for Base/Test (#27)

Add (mostly) complete documentation for Base/Test. This can be viewed as the
GitHub readme in the Base/Test directory.

A few other changes have been made:

* Removed the Time checksum class, as it's not used at all;

* Fixed message error in the TestList class in TestReport.cc;

* Cleaned up the Result code in TestResult.hh; and

* Removed most references to ReForm in Base.

Test/CMakeLists.txt

@@ -10,7 +10,6 @@ set(my_headers
    ${CMAKE_CURRENT_SOURCE_DIR}/TestChecksumIssueNumber.hh
    ${CMAKE_CURRENT_SOURCE_DIR}/TestChecksumLevel.hh
    ${CMAKE_CURRENT_SOURCE_DIR}/TestChecksumNumberT.hh
-   ${CMAKE_CURRENT_SOURCE_DIR}/TestChecksumTime.hh
    ${CMAKE_CURRENT_SOURCE_DIR}/TestPaths.hh
    ${CMAKE_CURRENT_SOURCE_DIR}/TestReport.hh
    ${CMAKE_CURRENT_SOURCE_DIR}/TestResult.hh

Test/TestChecksum.hh

@@ -173,18 +173,18 @@ private:
 } // namespace Checksum
 } // namespace Test
 
-#define TEST(CHKSM, RCRD) \
+#define TEST(CHKSM_OBJ, RCRD_FN) \
   { \
-    if (Test::Checksum::CHKSM.allow()) \
+    if (Test::Checksum::CHKSM_OBJ.allow()) \
     { \
-      Test::Checksum::CHKSM.RCRD; \
+      Test::Checksum::CHKSM_OBJ.RCRD_FN; \
     } \
   }
 
-#define TEST_if(CNDT, CHKSM, RCRD) \
+#define TEST_if(CNDT, CHKSM_OBJ, RCRD_FN) \
   { \
     if (CNDT) \
-      TEST(CHKSM, RCRD) \
+      TEST(CHKSM_OBJ, RCRD_FN) \
   }
 
 #endif // TEST_ON

Test/TestChecksumCondition.hh

 // (C) Copyright 2021 by Autodesk, Inc.
 
-#ifndef REFORM_CHECKSUMCONDITION_HH_INCLUDED
-#define REFORM_CHECKSUMCONDITION_HH_INCLUDED
+#ifndef BASE_CHECKSUMCONDITION_HH_INCLUDED
+#define BASE_CHECKSUMCONDITION_HH_INCLUDED
 
 #include <Base/Debug/DebOut.hh>
 #include <Base/Test/TestChecksum.hh>
 
 #if defined(TEST_ON)
 
-// The functions in this file are used to count the number of errors and warnings
-// and makes sense only if both the debug and test macro are on.
+// The functions in this file are used to count the number of errors and
+// warnings and makes sense only if both the debug and test macro are on.
 
-namespace Base {
+namespace Base
+{
 struct CodeLink;
-}//namespace Base
+} // namespace Base
 
-namespace Test {
-namespace Checksum {
+namespace Test
+{
+namespace Checksum
+{
 
 class Condition : public Object
 {
 public:
   Condition() : Object("Condition", L_STABLE), nmbr_(0), fail_nmbr_(0) {}
-    
-  virtual void record(const char* const _cndt, const Base::CodeLink& _lnk, 
-    const bool _rslt);
+
+  virtual void record(
+      const char* const _cndt, const Base::CodeLink& _lnk, const bool _rslt);
   virtual void record_number();
 
 protected:
@@ -32,15 +35,15 @@ protected:
   virtual Difference compare_data(const String& _old, const String& _new) const;
 
 protected:
-  int nmbr_; //number of all checked conditions
+  int nmbr_;      // number of all checked conditions
   int fail_nmbr_; // number of failed checked conditions
 };
 
 extern Condition condition;
 
-}//namespace Checksum
-}//namespace Test
+} // namespace Checksum
+} // namespace Test
 
-#endif//defined(TEST_ON)
+#endif // defined(TEST_ON)
 
-#endif//REFORM_CHECKSUMCONDITION_HH_INCLUDED
+#endif // BASE_CHECKSUMCONDITION_HH_INCLUDED

Test/TestChecksumLevel.hh

@@ -22,4 +22,4 @@ enum Level
 } // namespace Test
 #endif // TEST_ON
 
-#endif // REFORM_TESTCHECKSUMLEVEL_HH_INCLUDED
+#endif // BASE_TESTCHECKSUMLEVEL_HH_INCLUDED

Test/TestChecksumTime.hh

-// (C) Copyright 2021 by Autodesk, Inc.
-
-#ifndef BASE_TESTCHECKSUMTIME_HH_INCLUDED
-#define BASE_TESTCHECKSUMTIME_HH_INCLUDED
-#ifdef TEST_ON
-
-#include <Base/Test/TestChecksumNumberT.hh>
-#include <chrono>
-
-namespace Test
-{
-namespace Checksum
-{
-
-class Time : public NumberT<double>
-{
-public:
-  using Number = NumberT<double>;
-
-public:
-  Time(const char* const _name = "time", const Level _lvl = L_ALL)
-      : Number(_name, _lvl)
-  {
-  }
-
-  void start() { start_time_ = std::chrono::system_clock::now(); }
-  void record()
-  {
-    std::chrono::time_point<std::chrono::system_clock> end_time;
-    std::chrono::duration<double> time_diff_sec =
-        std::chrono::system_clock::now() - start_time_;
-    Number::record(Result::OK, time_diff_sec.count());
-  }
-
-private:
-  std::chrono::time_point<std::chrono::system_clock> start_time_;
-};
-
-} // namespace Checksum
-} // namespace Test
-
-#endif // TEST_ON
-#endif // BASE_TESTCHECKSUMTIME_HH_INCLUDED

Test/TestReport.cc

@@ -95,7 +95,7 @@ TestList::TestList(const char* _dir) : exp_test_nmbr_(0)
 {
   if (!fs::exists(_dir))
   {
-    std::cout << "Path " << root_dir_ << " does not exist!" << std::endl;
+    std::cout << "Path " << _dir << " does not exist!" << std::endl;
     exit(ES_ROOT_NOT_FOUND); // TODO: different error code?
   }
   root_dir_ = _dir;

Test/TestReport.hh

@@ -15,9 +15,10 @@ Process one or two test root directory arguments by extracting the list
 of tests inside each. Produce as follows:
 
 1. Test report (if one root directory has been specified)
-2. Test comparison (it two root directories have been specified)
+2. Test comparison (if two root directories have been specified)
 3. Update the first folder to match the second by copying and overriding test
-output.
+   output.
+
 An optional third argument can be passed to specify behavior affecting options
 (2) and (3) above. The values are as follow:
 

Test/TestResult.hh

@@ -10,39 +10,39 @@
 namespace Test {
 
 /*!
-Representation of a result in the test system, e.g., for a checksum, test run, 
+Representation of a result in the test system, e.g., for a checksum, test run,
 test list report, comparison.
 
 This might hold more information in the future, such as number of errors and
 warnings reported, etc. Hence it is more future-proof than an enum.
 */
 class Result
-{ 
+{
 public:
   enum Type // keep descriptions updated.
   {
-    OK,   
+    OK,
     WARNING,
     ERROR,
     FAILURE,
     CRASH,
-    HANG
+    HANG,
+    TYPE_NUMBER
   };
 
 public:
   Result(Type _type = OK) : type_(_type) {}
 
-  // Short Result description!
+  // Read in a short Result description
   template <class StreamT>
   friend inline StreamT& operator>>(StreamT& _is, Result& _rslt)
   {
     char c;
     _is >> c;
-    size_t descr_nmbr;
-    auto descr = descriptions(&descr_nmbr);
-    for (size_t i = 0; i < descr_nmbr; ++i)
+    auto descr = short_descriptions();
+    for (size_t i = 0; i < Result::Type::TYPE_NUMBER; ++i)
     {
-      if (descr[i][0] == c)
+      if (descr[i] == c)
       {
         _rslt = Result(Type(i));
         return _is;
@@ -55,18 +55,18 @@ public:
   template <class StreamT>
   friend inline StreamT& operator<<(StreamT& _os, const Result& _rslt)
   {
-    _os << descriptions()[_rslt.type()][0];
+    _os << short_descriptions()[_rslt.type()];
     return _os;
   }
 
-  // Return a Result description!
-  const char* message() const { return descriptions()[type_]; }
+  // Return a long Result description
+  const char* message() const { return long_descriptions()[type_]; }
 
   Type type() const { return type_; }
 
   bool ok() const { return type() == OK; }
 
-  //! Update the type to the more severe type from the input and this
+  //! Update the type to the more severe type (between this and the input)
   Result& operator+=(const Type _type)
   {
     if (type_ < _type)
@@ -86,22 +86,24 @@ public:
     return _a.type() != _b.type();
   }
 
-private: 
+private:
   Type type_;
 
 private:
-  static const char** descriptions(size_t* _nmbr = nullptr)
+  static const char** long_descriptions()
+  {
+    static const char* long_descr[] = {
+        "OK", "WARNING", "ERROR", "FAILURE", "CRASH", "HANG"
+    };
+    return long_descr;
+  }
+
+  static const char* short_descriptions()
   {
-    // There is a long and a short description. The short one is the first letter
-    // for the long one. For OK it is desirable to have a blank as short description,
-    // and this is the reason of the extra blank in " OK".
-    static const char* descr[] =
-    { " OK", "WARNING", "ERROR", "FAILURE" , "CRASH", "HANG" };
-    if (_nmbr != nullptr)
-      *_nmbr = std::end(descr) - std::begin(descr);
-    return descr;
+    static const char short_descr[] = { ' ', 'W', 'E', 'F', 'C', 'H' };
+    return short_descr;
   }
-}; 
+};
 
 }//namespace Test
 

Utils/BaseErrorInc.hh

 // (C) Copyright 2019 by Autodesk, Inc.
 
-//!\ReForm_SDK
 #ifndef DEFINE_ERROR
 #error This file should not be included directly, include the corresponding Outcome/Error header instead
 #endif

Utils/Environment.hh

@@ -6,12 +6,14 @@
 #include <string>
 #include <locale>
 
-namespace System {
-namespace Environment {
+namespace System
+{
+namespace Environment
+{
 
-/*! 
+/*!
 Get the value of an environment variable. This wraps around getenv() in
-a portable, secure (and in future) thread-safe way. If the variable is 
+a portable, secure (and in future) thread-safe way. If the variable is
 undefined, return an empty string.
 
 Returns false if the variable is undefined, the input string is unchanged.
@@ -27,8 +29,8 @@ inline std::string variable(const char* const _vrbl_name)
 }
 
 //! Same as above, but returns a default string if the variable is undefined.
-inline std::string variable(const char* const _vrbl_name, 
-  const char* const _vrbl_dflt)
+inline std::string variable(
+    const char* const _vrbl_name, const char* const _vrbl_dflt)
 {
   std::string vrbl(_vrbl_dflt);
   variable(_vrbl_name, vrbl);
@@ -36,12 +38,12 @@ inline std::string variable(const char* const _vrbl_name,
 }
 
 /*!
-Define a "scoped" custom locale session. 
+Define a "scoped" custom locale session.
 */
 class LocaleSession
 {
 public:
-  //default session locale is "C" (i.e., "." is the decimal point)
+  // default session locale is "C" (i.e., "." is the decimal point)
   LocaleSession(const char* const _ssn_lcle = "C");
   ~LocaleSession();
 
@@ -50,13 +52,12 @@ private:
   std::string c_lcl_bckp_;
 };
 
-
 //! Return the system time in a string
 std::string time();
 //! A version of the time function that does not require allocations
 void time(const size_t bffr_size, char* const bffr);
 
-}//namespace Environment 
-}//namespace System
+} // namespace Environment
+} // namespace System
 
-#endif//REFORM_ENVIRONMENT_HH_INCLUDED
+#endif // BASE_ENVIRONMENT_HH_INCLUDED