% Given a set of results from utp_run, this function attaches additional
% documentation for each unit test.
function newResults = document_utp_results(results)
  
  
  for kk=1:numel(results)
    fprintf(1, '+ %d documenting %s/%s/%s\n', kk, results(kk).class, results(kk).method, results(kk).num);
    newResults(kk) = readUTP(results(kk));
  end
  
end


function result = readUTP(result)
  
  filename = result.file;
  utpFcn   = result.utp;
  
  
  % parse the utp fcn
  parts = regexp(utpFcn, filesep, 'split');
  utp = parts{end};
  
  if strcmp(utp, 'xx')
    % the utp failed to run
    result.doc.desc = '';
    result.doc.syntax = '';
    result.doc.syntaxCode = '';
    result.doc.algo = '';
    result.doc.algoCode = '';
    return;
  end
  
  
  fd = fopen(filename);
  if fd < 0
    warning('Failed to open %s', filename);
    
  end
  
  fulltxt = {};
  while ~feof(fd)
    fulltxt = [fulltxt {fgetl(fd)}];
  end
  
  fclose(fd);
  
  % parse the txt for this test only
  
  % 1) find the utp_XX
  % 2) backtrack to find <TestDescription>
  % 3) read forward to get the end of the fcn (count even closing end's)
  
  res = regexp(fulltxt, ['result\s*=\s*' utp]);
  fcnLine = find(~cellfun('isempty', res));
  
  % backtrack to look for the test description start
  line = findLine(fulltxt, '<TestDescription>', fcnLine, true);
  
  % parse out the test description
  result.doc.desc = parseSection(fulltxt(line:end), utp, '<TestDescription>', '</TestDescription>', result.class, result.method, true, true);
    
  % parse out the syntax test
  result.doc.syntax = parseSection(fulltxt(line:end), utp, '<SyntaxDescription>', '</SyntaxDescription>', result.class, result.method, true, true);
  
  % parse out syntax code
  result.doc.syntaxCode = parseSection(fulltxt(line:end), utp, '<SyntaxCode>', '</SyntaxCode>', result.class, result.method, false, false);
  
  % parse out the algorithm test
  result.doc.algo = parseSection(fulltxt(line:end), utp, '<AlgoDescription>', '</AlgoDescription>', result.class, result.method, true, true);
  
  % parse out algorithm code
  result.doc.algoCode = parseSection(fulltxt(line:end), utp, '<AlgoCode>', '</AlgoCode>', result.class, result.method, false, false);
  
  
  
end

function line = findLine(lines, tag, startLine, backwards)
  
  
  % backtrack to look for the test description start
  line = startLine;
  if backwards
    while line > 0      
      try
      if strfind(lines{line}, tag)
        break;
      end
      catch
        lines
        line
        tag
      end
      line = line - 1;
    end
  else
    while line <= numel(lines)      
      if strfind(lines{line}, tag)
        break;
      end      
      line = line + 1;
    end
  end
  
end

function desc = parseSection(lines, utp, startTag, endTag, class, method, stripComments, trimLines)
  
  % go forward capturing the description until we hit end of the
  % description
  line = 1;
  desc = '';
  foundStart = false;
  while line < numel(lines)
    if strfind(lines{line}, startTag)
      foundStart = true;
    end
    if foundStart
      lineTxt = lines{line};
      if stripComments
        lineTxt = strrep(lineTxt, '%', '');
      end
      lineTxt = regexprep(lineTxt, ['%*\s*' startTag], '');
      lineTxt = regexprep(lineTxt, ['%*\s*' endTag], '');
      lineTxt = strrep(lineTxt, '<METHOD>', ['[' class '/' method ']']);
      if trimLines
        lineTxt = strtrim(lineTxt);
      end
      desc = [desc sprintf('%s\n', lineTxt)];
    end
    if strfind(lines{line}, endTag)
      break;
    end
    line = line + 1;
  end
  
  desc = strtrim(desc);
  
  
end