Commits

thom...@gmail.com  committed 0404895

Add examples + documentation. also tweaked verbosity a little (still not really the right way to do verbosity).

  • Participants
  • Parent commits 4a322d4

Comments (0)

Files changed (1)

 % If the output of some function will change each time you call it, for
 % instance if it includes a random number or a stack trace, you can put ***
 % (three asterisks) where the changing element should be.  This acts as a
-% wildcard, and will match anything.
+% wildcard, and will match anything.  See the example below.
+%
+% EXAMPLES:
+%
+% Running 'doctest doctest' will execute these examples and test the
+% results.
+%
+% >> 1 + 3
+% 
+% ans =
+% 
+%      4
+%
+%
+% Note the two blank lines between the end of the output and the beginning
+% of this paragraph.  That's important so that we can tell that this
+% paragraph is text and not part of the example!
+%
+% If there's no output, that's fine, just put the next line right after the
+% one with no output.  If the line does produce output (for instance, an
+% error), this will be recorded as a test failure.
+%
+% >> x = 3 + 4;
+% >> x
+%
+% x =
+%
+%    7
+%
+%
+% Exceptions:
+% doctest can deal with errors, a little bit.  For instance, this case is
+% handled correctly:
+%
+% >> not_a_real_function(42)
+% ??? Undefined function or method 'not_a_real_function' for input
+% arguments of type 'double'.
+%
+%
+% But if the line of code will emit other output BEFORE the error message,
+% the current version can't deal with that.  For more info see Issue #4 on
+% the bitbucket site (below).  Warnings are different from errors, and they
+% work fine.
+%
+% Wildcards:
+% If you have something that has changing output, for instance line numbers
+% in a stack trace, or something with random numbers, you can use a
+% wildcard to match that part.
+%
+% >> dicomuid
+% 1.3.6.1.4.1.***
+%
 %
 % LIMITATIONS:
 %
 % because I haven't found a good way to mark these subsequent lines as
 % part-of-the-source-code rather than part-of-the-result.
 % 
+% When you're working on writing/debugging a Matlab class, you might need
+% to run 'clear classes' to get correct results from doctests (this is a
+% general problem with developing classes in Matlab).
+%
+% It doesn't say what line number/file the doctest error is in.  This is
+% because it uses Matlab's plain ol' HELP function to extract the
+% documentation.  It wouldn't be too hard to write our own comment parser,
+% but this hasn't happened yet.  (See Issue #2 on the bitbucket site,
+% below)
+%
+
+%
+% The latest version from the original author, Thomas Smith, is available
+% at http://bitbucket.org/tgs/doctest-for-matlab/src
+
+verbose = 0;
 
 to_test = { func_or_class };
 
         sprintf('%s.%s', func_or_class, theMethods{I}) ];
 end
 
-to_test
+% to_test
 
 result = [];
 
     result = [result, do_test(to_test{I})];
 end
     
-test_anything(result, 1);
+test_anything(result, verbose);
 
 
 end