fix(Schema): isequal_ctype docstring

Fix indentation, example block
and verbose output.

Util/Schema/isequal_ctype.m

@@ -1,57 +1,60 @@
 function [bool] = isequal_ctype(a, b),
-    % function [bool] = isequal_ctype(a,b),
-    %
-    % An enhanced isequal that compare type and content.
-    % This will not compare types of individual [cell,struct]
-    % [indexes,fieldnames]. For this, use treeDiff.
-    %
-    % Inputs:
-    %
-    % a - any non-class matlab variable.
-    % b - any non-class matlab variable.
-    %
-    % Outputs:
-    %
-    % bool - a boolean number representing if the type and content of
-    %        a and b are the same.
-    %
-    % Example:
-    % >>> a = 0,b=false;
-    % >>> assert(~isequal_ctype(a,b))
-    % >>> a = {0,int8(1),single(2),3.}, b = {false,int8(1),single(2),3.}
-    % >>> assert(isequal_ctype(a,b))
-    % >>> b{4} = 4.
-    % >>> assert(~isequal_ctype(a,b))
-    % >>> %matlab caveat - use treeDiff.m instead
-    % >>> a = struct('x',false), b = struct('x',0)
-    % >>> assert(isequal_ctype(a,b))
-    %
-    % author: hugo.oliveira@utas.edu.au
-    %
+% function [bool] = isequal_ctype(a,b),
+%
+% An enhanced isequal that compare type and content.
+% This will not compare types of individual [cell,struct]
+% [indexes,fieldnames]. For this, use treeDiff.
+%
+% Inputs:
+%
+% a - any non-class matlab variable.
+% b - any non-class matlab variable.
+%
+% Outputs:
+%
+% bool - a boolean number representing if the type and content of
+%        a and b are the same.
+%
+% Example:
+% a = 0;
+% b=false;
+% assert(~isequal_ctype(a,b))
+% a = {0,int8(1),single(2),3.};
+% b = {false,int8(1),single(2),3.};
+% assert(isequal_ctype(a,b))
+% b{4} = 4.;
+% assert(~isequal_ctype(a,b))
+% %matlab caveat - use treeDiff.m instead
+% a = struct('x',false);
+% b = struct('x',0);
+% assert(isequal_ctype(a,b))
+%
+% author: hugo.oliveira@utas.edu.au
+%
 
-    % Copyright (C) 2019, Australian Ocean Data Network (AODN) and Integrated
-    % Marine Observing System (IMOS).
-    %
-    % This program is free software: you can redistribute it and/or modify
-    % it under the terms of the GNU General Public License as published by
-    % the Free Software Foundation version 3 of the License.
-    %
-    % This program is distributed in the hope that it will be useful,
-    % but WITHOUT ANY WARRANTY; without even the implied warranty of
-    % MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-    % GNU General Public License for more details.
-    %
-    % You should have received a copy of the GNU General Public License
-    % along with this program.
-    % If not, see <https://www.gnu.org/licenses/gpl-3.0.en.html>.
-    %
+% Copyright (C) 2019, Australian Ocean Data Network (AODN) and Integrated
+% Marine Observing System (IMOS).
+%
+% This program is free software: you can redistribute it and/or modify
+% it under the terms of the GNU General Public License as published by
+% the Free Software Foundation version 3 of the License.
+%
+% This program is distributed in the hope that it will be useful,
+% but WITHOUT ANY WARRANTY; without even the implied warranty of
+% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+% GNU General Public License for more details.
+%
+% You should have received a copy of the GNU General Public License
+% along with this program.
+% If not, see <https://www.gnu.org/licenses/gpl-3.0.en.html>.
+%
 
-    atype = whichtype(a);
-    btype = whichtype(b);
-    bool = isequal(atype, btype);
+atype = whichtype(a);
+btype = whichtype(b);
+bool = isequal(atype, btype);
 
-    if bool,
-        bool = isequaln(a, b);
-    end
+if bool,
+    bool = isequaln(a, b);
+end
 
 end

batchTesting.m

@@ -1,16 +1,19 @@
-function batchTesting(parallel)
-% function batchTesting(parallel)
+function runTestCoverage(parallel,print_stats)
+% function runTestCoverage(parallel)
 %
-% Execute all the xunit Test functions of the toolbox
-% in batch mode.
+% Execute all the xunit Test functions
+% and docstring tests
 %
 % Inputs:
 %
-% parallel - true for parallel execution
+% parallel[bool] - true for parallel execution.
+% print_stats[bool] = true for printing statistics.
 %
 % Example:
 %
-% %batchTesting(1)
+% % trigger all tests hiding the output
+% % and running all serially
+% %batchTesting(0,1);
 %
 % author: hugo.oliveira@utas.edu.au
 %
@@ -31,97 +34,165 @@ function batchTesting(parallel)
 % along with this program.
 % If not, see <https://www.gnu.org/licenses/gpl-3.0.en.html>.
 %
+narginchk(0, 2)
 
-csplit = strsplit(mfilename('fullpath'),[ filesep 'batchTesting']);
+if nargin == 0
+    parallel = false;
+    print_stats = true;
+elseif nargin == 1
+    print_stats = true;
+end
+
+csplit = strsplit(mfilename('fullpath'), [filesep 'batchTesting']);
 root_folder = csplit{1};
 addpath([root_folder filesep 'Util' filesep 'Path'])
 setToolboxPaths(root_folder)
 
 try
-    results = runAllTests(parallel)%do not supress report output
-catch
-    error('Tests failed')
+    sdisp('Executing `xunit` tests...')
+    results = runAllTests(parallel);
+    total_xunit_tests = length(results);
+catch me
+    sdisp('`xunit` tests aborted. Please investigate the error:')
+    rethrow(me)
+end
+
+xunit_failed = [results(:).Failed];
+xunit_n_failed = sum(xunit_failed);
+xunit_skipped = ~xunit_failed & [results(:).Incomplete];
+xunit_n_skipped = sum(xunit_skipped);
+[xunit_failed_files, xunit_failed_tests, xunit_failed_lines] = get_xunit_stats(results(xunit_failed));
+[xunit_skipped_files, xunit_skipped_tests, xunit_skipped_lines] = get_xunit_stats(results(xunit_skipped));
+
+try
+    sdisp('Executing `docstring` tests...')
+    [ok, wrong_files, total_docstring_tests, error_msgs, missing_comment, missing_example] = checkDocstrings(toolboxRootPath());
+catch me
+    sdisp('Could not run `docstring` tests!')
+    rethrow(me)
 end
 
-failed = {'    Tests failed:\n'};
-c = 2;
+docstring_n_failed = length(wrong_files);
+docstring_n_skipped = length(missing_comment) + length(missing_example);
+
+failed_files = [xunit_failed_files, wrong_files];
+failed_tests = [xunit_failed_tests, wrong_files];
+failed_lines = [xunit_failed_lines, get_docstring_failed_lines(error_msgs)];
 
-%pretty print the results of failed tests.
-for k = 1:length(results)% loop through all results
-    ktest = results(k); %get k-results
+total_tests = total_xunit_tests + total_docstring_tests;
+total_failed = xunit_n_failed + docstring_n_failed;
+total_skipped = xunit_n_skipped + docstring_n_skipped;
 
-    if ~ktest.Passed
-        fparam = extract_param(ktest.Name); % extract all test parameters
-        fnames = fieldnames(fparam); %get parameter names
-        fnames = fnames(2:end); % remove the testname from the list
+total_missing_comment = length(missing_comment);
+total_missing_docstrings = length(missing_example);
 
-        %now create a pretty string
-        fstr = [repmat(' ', 1, length(failed{1})) fparam.testname ':\n'];
-        lfstr = length(fstr)
+if ~print_stats
+    return
+end
 
-        for kk = 1:length(fnames)
-            fstr = [fstr repmat(' ', 1, lfstr) fnames{kk} '->' fparam.(fnames{kk}) '\n'];
+sdisp('    ')
+sdisp('    ')
+sdisp('----IMOS toolbox Test Coverage Summary----')
+sdisp('    Total number of tests: %d (%d xunit, %d docstrings)',total_tests,total_xunit_tests,total_docstring_tests);
+sdisp('    Total number of failed tests: %d (%d xunit, %d docstrings)',total_failed,xunit_n_failed,docstring_n_failed);
+sdisp('    Total number of skipped tests: %d (%d xunit, %d docstrings)',total_skipped,xunit_n_skipped,docstring_n_skipped);
+sdisp('    ');
+if total_failed > 0
+    sdisp('Failed tests are:')
+    for k=1:length(failed_files)
+        if strcmp(failed_files{k},failed_tests{k})
+            sdisp('    file/test=%s,line=%s',failed_files{k},failed_lines{k})
+        else
+            sdisp('    file=%s,test=%s,line=%s',failed_files{k},failed_tests{k},failed_lines{k})
         end
+    end
+end
+
 
-        fstr = [fstr '\n'];
-        failed{c} = fstr; % store the string for subsequent failed tests if any
-        c = c + 1;
+if total_skipped > 0
+    if ~isempty(xunit_skipped_files)
+        sdisp('Skipped xunit tests are:')
+        for k=1:length(xunit_skipped_files)
+            sdisp('    test=%s',xunit_skipped_files{k})
+        end
+    end
+    if ~isempty(missing_comment)
+        sdisp('Skipped docstring tests are:')
+        for k=1:length(missing_comment)
+            sdisp('    file=%s, reason: missing docstring block',missing_comment{k});
+        end
     end
 
+    if ~isempty(missing_example)
+        for k=1:length(missing_example)
+            sdisp('    test=%s, reason: missing example block',missing_example{k});
+        end
+    end
 end
 
-if length(failed) > 1
-    error(sprintf(strjoin(failed)))
+
 end
 
+function [failed_files, failed_tests, failed_lines] = get_xunit_stats(results)
+n = length(results);
+failed_files = cell(1, n);
+failed_tests = cell(1, n);
+failed_lines = cell(1, n);
+
+for k = 1:n
+    test = results(k);
+    failed_files{k} = get_testfile(test);
+    failed_tests{k} = get_testname(test);
+    failed_lines{k} = get_blameline(test);
 end
 
-function params = extract_param(namestr)
-% function extract_param(namestr)
-%
-% Extract the name parameters used in the test
-% based on the name of the test.
-%
-% Inputs:
-%
-% namestr - the name of the test in the TestResult array.
-%
-% Example:
-%
-% testname_str='mytest(myparam='abc',myparam2='cba',folder='p__home_user_S');
-% params=extract_param(testname_str);
-% assert(strcmpi(params.testname,'mytest'))
-% assert(strcmpi(params.myparam,'abc'))
-% assert(strcmpi(params.myparam2,'cba'))
-% assert(strcmpi(params.folder='/home/user'))
-%
-% author: hugo.oliveira@utas.edu.au
+end
+
+function [clines] = get_docstring_failed_lines(error_msgs)
+clines = cell(1, length(error_msgs));
+
+for k = 1:length(clines)
+    s = find(error_msgs{k} == '(', 1);
+    e = find(error_msgs{k} == ')', 1);
+    clines{k} = error_msgs{k}(s:e);
+end
+
+end
+
+function file = get_testfile(r)
+
+try
+    file = r.Details.DiagnosticRecord.Exception.stack(1).file;
+catch
+    file = 'Unknown file';
+end
+
+end
 
-params = struct();
+function testname = get_testname(r)
 
-tmp = strsplit(namestr, '(');
-tmp2 = strsplit(tmp{1}, fileSep);
-params.testname = tmp2{end};
+try
+    testname = r.Details.DiagnosticRecord.Stack(1).name;
+catch
+    try
+        testname = replace(r.Details.DiagnosticRecord.EventLocation, '/', '.');
+    catch
+        testname = 'Unknown test';
+    end
+end
 
-pcell = strsplit(namestr, ',');
+end
 
-tmp = strsplit(pcell{1}, '(');
-tmp2 = strsplit(tmp{end}, '=');
-pname = tmp2{1};
-pval = tmp2{2};
-params.(pname) = pval;
+function blameline = get_blameline(r)
 
-for k = 2:length(pcell) - 1
-    tmp = strsplit(pcell{k}, '=');
-    pname = tmp{1};
-    pval = tmp{2};
-    params.(pname) = pval;
+try
+    blameline = r.Details.DiagnosticRecord.Stack(1).line;
+catch
+    blameline = 'Unknown line';
 end
 
-tmp = strsplit(pcell{end}, ')');
-tmp2 = strsplit(tmp{1}, '=');
-pname = tmp2{1};
-pval = tmp2{2};
-params.(pname) = pval;
+end
 
+function sdisp(varargin)
+    disp(sprintf(varargin{:}));
 end