run_tsuite is the main driver for running a test suite.

   mode argument controls level of detail of output as follows:
    * 'silent'    -- no output.
    * 'minimal'   -- print test case summary.
    * 'normal'    -- print names of failed  tests and test case summary.
    * 'verbose'   -- print all test names and their status, and test case summary.
    * 'details'   -- print diagnostics while running tests as well all test names 
                     and their status, and test case summary.

   If logfile is specified, output is written to logfile.
   Note: Info printed by tested functions is still displayed to console.

   run_tcase is the main driver for running a test case.

   tcase is one of the following:
    * string containing name of test case (i.e. file/function) to run.
    * function handle of the test case to run (@tcase).
    * a test case struct (tcase_s).

   The mode argument controls level of detail of output as follows:
    * 'silent'    -- no output.
    * 'minimal'   -- print test case summary.
    * 'normal'    -- print names of failed  tests and test case summary.
    * 'verbose'   -- print all test names and their status, and test case summary.
    * 'details'   -- print diagnostics while running tests as well all test names 
                     and their status, and test case summary.

   If logfile is specified, output is written to logfile.
   Note that info printed by tested functions is still displayed to command window.
 
   The test_list argument allows the optional execution of specific test(s)
   within test case.  By default, all tests within a test case are run.  
   If test_list is a string or cell array of strings, then the tests with the 
   matching names are run.  If test_list is a number or cell array of numbers, 
   then the tests with matching order in the test list are run, i.e. 
   if test_list = {1, 3}, then the first and third tests are run.  If items
   in test_list that do not match by test name or test order number are ignored.

   Description of variables used in MUnit.

 TOOLBOX
    munit/munit

 CATEGORY

   mode controls the level of detail of print output as follows:
    * 'silent'    -- no output.
                       * errors
    * 'minimal'   -- print
                       * errors
                       * test case and/or test suite summaries.
    * 'normal'    -- print 
                       * errors
                       * test results report of failed  tests
                       * test case and/or test suite summaries.
    * 'verbose'   -- print 
                       * errors
                       * full test results report.
                       * test case and/or test suite summaries.
    * 'details'   -- print
                       * errors
                       * diagnostics while running tests
                       * full test results report.
                       * test case and/or test suite summaries.

   Note: For all modes, info printed durning execution of tested functions 
         is displayed to command window.

   The tcase variable specifies a test case and can be one of the 
   following types:
     * a string containing name of a test case function
     * a function handle (@tcase) to a test case function
     * a test case struct (tcase_s).

   trstatus can take on the following values: 
     *  1   --  'SUCCESS'
     *  0   --  'FAIL'
     * -1   --  'ERROR'
     * NaN  --  otherwise

   The tsuite variable specifies a test suite and can be one of the 
   following types:
     * a string containing name of a test suite function
     * a function handle (@tsuite) to a test suite function
     * a test suite struct (tsuite_s).

   MUnit template files:

    * files: tsuite_template.m
             tcase_template.m

   MATLAB struts used in MUnit.

 TOOLBOX
    munit/munit

 CATEGORY

   The test result summary struct (tc_summary_s) summarizes the execution of
   tests in a test case and has the following fields:
   * ntests  -- number of tests run
   * npass   -- number of tests passed
   * nfails  -- number of test failed
   * nerrs   -- number of tests returning errors
   * percentPassed -- percent of tests passed
   * failedTests -- list of failed tests (cell string array)
   * failedTestNums -- ordinal number of the failed test in test case (vector).
   * erroredTests -- list of tests that errored (cell string array)
   * erroredTestNums -- ordinal number of the erroed test in test case (vector).
   * elapsedWallTime -- elapsed wall time to run test case
   * elapsedCPUTime -- elapsed cpu time to run test case.

   The MU_summarize_tresults function creates a tc_summary_s struct
   and updates all fields, except elapsedwalltime and elapsedcputime.

   tcase_s struct has fields:
   * name     -- name of test case (string)
   * pathstr  -- optional path to location of tcase mfile (string).
   * tests    -- cell array of function handles to test functions (@tfh).
   * tresults -- test case results (vector of tresult_s).

   The MU_tcase_new function creates and initializes an empty tcase_s struct.

   tresult_s struct contains the results of an executed test and has
   the following fields:
     * trstatus -- test result status code.
     * tcname   -- name of associated test case.
     * testfh   -- function handle of test.
     * message  -- supplementary message associated with test execution.

   tresult_s struct contains the results of an executed test suite and has
   the following fields:
     * tcase      -- name of associated test case.
     * tresults   -- vector of tresult_s structs for associated test case.
     * tc_summary -- tc_summary_s struct for associated test case.

   The test result summary struct (ts_summary_s) summarizes the execution of
   tests in a suite of test cases and has the following fields:
     * tsname  -- name of test suite.
     * ntcases -- number of test cases run.
     * ntests  -- number of tests run.
     * npass   -- number of tests passed.
     * nfails  -- number of test failed.
     * nerrs   -- number of tests returning errors.
     * percentPassed -- percent of tests passed.

   tsuite_s struct has fields:
   * name         -- name of test suite (string).
   * pathstr      -- optional path to location of tsuite mfile (string).
   * tcases       -- vector of test case structures (tcase_s).
   * trsummaries  -- optional path to location of tcase mfile (string).

   The MU_tsuite_new function creates and initializes an empty tsuite_s struct.

   Functions in MUnit library used to assert the comparison of actual test 
   results to expected values.

   Functions in MUnit library used for creating and print test results and
   tcase/tsuite summaries.

   Functions in MUnit library used to create, run, summarize and report a test
   case:

   Functions in MUnit library used to create, run, summarize and report a test suite.

   Functions in MUnit library used for various utility purposes.

   The MUnit library is a collection of functions to be used implement test
   cases and test suites, assert tests, and compile and print test results.
   The functions in the MUnit library are intended to be use in creating and
   executing test via the test case and test suite framework and are not
   indeeded to be called directly from the command line.  Functions in the
   MUnit library are prefixed by MU_.

   Functions within the MUnit library are categorized as follows:
     lib.assert      -- Assert functions to compare of actual test results to expected values.
     lib.tcase       -- Functions for implementing a test case.
     lib.tsuite      -- Functions for implementing a test suite.
     lib.report      -- Functions for creating and printing test results and test case/suite summaries.

 TOOLBOX
    munit/munit

 CATEGORY

   Add detailed introduction.

   MUNIT:AssertionFailedError indicates that an assertion has
   failed.

   MUNIT:InvalidArgumentType indicates that the argument to
   function has invalid data type.

   MUNIT:MissingRequiredArgument indicates that a required argument
   is missing from the argument list to the function call.

   MUNIT:UnknownTest indicates that a test specified by a test function
   handle (@tfh) or alternatively by the file test_location does not 
   exist or could not be found.

   MUNIT:UnknownTestCase indicates that a test case specified 
   by a file name, function handle, or test case struct does not
   exist or could not be found.

   MUNIT:UnknownTestSuite indicates that a test suite specified 
   by a file name, function handle, or test suite struct does not
   exist or could not be found.

   MATLAB error message ids used in MUnit.

 TOOLBOX
    munit/munit

 CATEGORY

   The MUnit driver applications are functions to be run from the 
   command shell to execute a test case or a test suite.

   Driver applications include:
     * run_tcase
     * run_tsuite

   The MUnit utility applications are functions to be run from the 
   command shell to analyze and list a test case or a test suite.

   Utility applications include:
     * list_tcase
     * list_tsuite

   The MUnit test framework consists of several applications
   to execute and manage the test cases and test suites.
   The application functions are categorized as:

   * Drivers   -- execute test cases and test suites.
   * Utilities -- manage test cases and test suites.

 TOOLBOX
    munit/munit

 CATEGORY

   The MUnit API is a library of functions and associated
   structures, error codes and standard variable names
   that implement the MUnit test framework.

   MUnit is a framework for unit testing of MATLAB functions.

   Function runs the test cases in the test suite ts.
  
   See MUnit_Variables for a description of mode.

   Note: For all modes, info printed by tested functions is still displayed 
         to command window.

   Function creates and returns a new test suite structure.
   name must be specified and non-blank.

   tsuite_s struct has fields:
     * name        -- name of test suite (string).
     * tcases      -- vector of tcase structures (tcase_s).
     * trsummaries -- vector of trsummary structs (trsummary_s).
     
   Note: length(ts.trsummaries) = length(ts.tscases)
   after run of tsuite.

   Function prints the test cases for the specified test suite.

   Function creates via MU_tcase_new and loads the tsuite found 
   in tsuite file (tsuite) or function handle (@tsuite).

   Function adds a tcase to a tsuite structure.

   Function creates and initializes a test result struct (tresult_s).

   Test result struct has the following fields:
     * trstatus -- result of test execution.
     * tcname   -- name of associated test case.
     * testfh   -- function handle of test.
     * message  -- supplementary message associated with test execution.

   Function runs a specified test for test case.
  
   See MUnit_Variables for a description of mode.

   Function runs the tests in a test case and returns the
   test results for each test.

   See MUnit_Variables for a description of mode.

   Note: For all modes, info printed by tested functions is still displayed 
         to command window.

   The tests_to_run argument allows the optional execution of specific test(s)
   within test case.  By default, all tests within a test case are run.  
   If tests_to_run is not empty, then only the tests with the 
   matching names are run.  

   Function creates and returns a new (empty) test case structure tcase_s.

   tcase_s structure has fields:
   * name     -- name of test case (string).
   * pathstr  -- optional path to location of tcase mfile (string).
   * tests    -- cell array of function handles to test functions.
   * tresults -- test case results (vector of tresult_s).

   name is the only required argument.  
   pathstr, tests, and tresults are initialized to empty.

   Function prints the tests for the specified test.

   Function creates via MU_tcase_new and loads the tcase found 
   in tcase file (tcase) or function handle (@tcase).

   Function adds a test to a test case by verifying that the function handle to
   the test function exists, and, if successful, adds its test function handle
   to the set of tests for the test case tc. To verify the existance of the 
   function handle tfh, a check is made to determine if a function with a name
   associated with the tfh is found in the test case file ( = tc.name).
  
   Alternatively, if test_location is specified, the test referenced by @tfh
   may reside in a file other than the the tcase function file.
   A check is made to verify that test function associated with @tfh exists 
   in the file specitifed by test_location.

   Function summarizes the test case summaries contained in the ts_results 
   vector and returns the test suite summary in ts_summary struct.
   
   Test suite summary struct (ts_summary_s) has the following fields:
     * tsname  -- name of associated test suite.
     * ntcases -- number of test cases.
     * ntests  -- number of tests run.
     * npass   -- number of tests passed.
     * nfails  -- number of test failed.
     * nerrs   -- number of tests returning errors.
     * percentPassed -- percent of tests passed.

   Function summarizes the results of the test results in the
   tresults vector and returns summary in test result summary struct.
   
   Test result summary struct (tc_summary_s) struct has the following fields:
   * tcname  -- name of associated test case
   * ntests  -- number of tests run
   * npass   -- number of tests passed
   * nfails  -- number of test failed
   * nerrs   -- number of tests returning errors
   * percentPassed -- percent of tests passed
   * failedTests -- list of failed tests (cell string array)
   * failedTestNums -- ordinal number of the failed test in test case (vector).
   * erroredTests -- list of tests that errored (cell string array)
   * erroredTestNums -- ordinal number of the erroed test in test case (vector).
   * elapsedWallTime -- elapsed wall time to run test case
   * elapsedCPUTime -- elapsed cpu time to run test case.

   Function prints the summary for test suite.

   See MUnit_Variables for a description of mode.

   Function prints the test results in the tresults vector.

   See MUnit_Variables for a description of mode.

   Function prints the test results in the tresults vector.

   See MUnit_Variables for a description of mode.

   Function prints a summary of a test case run.

   See MUnit_Variables for a description of mode.

 TOOLBOX
     munit/munit

 CATEGORY
   MUNIT Library:  Reporting Functions

   Function lookups and returns the numeric test result status code for 
   specified test result status name as follows:

     * 'SUCCESS'  = 1
     * 'FAIL'     = 0
     * 'ERROR'    = -1
     *  otherwise = NaN;

   Function lookups and returns the numeric mode code for 
   for specified mode as follows:

    * 'silent'        = 1
    * 'minimal'       = 2
    * 'normal'        = 3
    * 'verbose'       = 4
    * 'details'       = 5
    * 'stoponerror'   = 6

   stoponerror mode always execution to stop upon error and display the stack
   leading up to the error.

   Function is a wrapper function that encodes the function name and line number 
   where an assertion error occurred along with supplmental message into error 
   string and then calls  MU_fail which throws an assertion error.

   Function throws the MUNIT:AssertionFailedError and passes the
   specified message.

   Function checks that expected and actual values are equal within
   numsigdig sigificiant digits.  If not, it calls MU_fail to throw 
   MUNIT:AssertionFailedError.

   mode argument controls level of detail of output as follows:
    'details'   = print diagnostics while running tests as well all test names 
                  and their status, and test case summary.
    otherwise, no output printed.

   Function checks actual value evaluates to Boolena true.
   If not, it calls MU_fail to throw MUNIT:AssertionFailedError.

   Function checks actual value is not empty.
   If empty, it calls MU_fail to throw MUNIT:AssertionFailedError.

   Function checks that expected and actual values are equal, treating
   NaNs as equals.  If not, it calls MU_fail to throw 
   MUNIT:AssertionFailedError.

   Function checks that expected and actual values are equal.  If not,
   it calls MU_fail to throw MUNIT:AssertionFailedError.

   Function checks actual value is empty.
   If not empty, it calls MU_fail to throw MUNIT:AssertionFailedError.

   Function checks that expected and actual values are equal within
   fuzzy tolerance.  If not, it calls MU_fail to throw 
   MUNIT:AssertionFailedError.

   fuzzy_diff compares two arrays and allows approximate equality when strict
   equality may not exist due to minor differences due to rounding errors.  
   fuzzy_diff subtracts two arrays and identifies those elements whose 
   differences exceed the fuzzy tolerance threshold.  

   The function has 2 modes of operation specified via mode:
      detailed  = return an array of size(a) with elements 
                   = 0,   for differences between a and b <  fuzzy_tolerance
                   = a-b, for differences between a and b >= fuzzy_tolerance
      summary   = return a number whose values 
                   = 0, for no differences within fuzzy_tolerance
                   > 0, number of elements >= fuzzy_tolerance

   Function evaluates the expression in the caller's workspace and
   evaluates whether it is true or not.
   If not true, it calls MU_fail to throw MUNIT:AssertionFailedError.

   Function checks that expected and actual error message ids are equal.  If not,
   it calls MU_fail to throw MUNIT:AssertionFailedError.

   list_tsuite is a utility application for listing test cases in a test suite.

   tsuite is one of the following:
    * string containing name of test case (i.e. file/function) to run.
    * function handle of the test case to run.
    * a test case struct.

   If logfile is specified, output is written to logfile.

   list_tcase is a utility application for listing tests in a test case.

   tcase is one of the following:
    * string containing name of test case (i.e. file/function) to run.
    * function handle of the test case to run.
    * a test case struct.

   If logfile is specified, output is written to logfile.