Commits

Anonymous committed 50a175d

Updated readme, added output example

Comments (0)

Files changed (2)

       end
   
   Save that to 'add7.m'.  Now you can say 'doctest add7' and it will run
-  'add7(3)' and make sure that it gets back 'ans = 10'.
+  'add7(3)' and make sure that it gets back 'ans = 10'.  It prints out
+  something like this:
+ 
+  TAP version 13
+  1..1
+  ok 1 - add7(3)
+ 
+  This is in the Test Anything Protocol format, which I guess is mostly
+  used by Perl people, but it's good enough for now.  See testanything.org.
  
   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)
+ 
 
+Result of running 'doctest doctest':
+>> doctest doctest
+TAP version 13
+1..5
+ok 1 - "1 + 3"
+ok 2 - "x = 3 + 4;"
+ok 3 - "x"
+ok 4 - "not_a_real_function(42)"
+ok 5 - "dicomuid"
+
 %     end
 % 
 % Save that to 'add7.m'.  Now you can say 'doctest add7' and it will run
-% 'add7(3)' and make sure that it gets back 'ans = 10'.
+% 'add7(3)' and make sure that it gets back 'ans = 10'.  It prints out
+% something like this:
+%
+% TAP version 13
+% 1..1
+% ok 1 - add7(3)
+%
+% This is in the Test Anything Protocol format, which I guess is mostly
+% used by Perl people, but it's good enough for now.  See <a
+% href="http://testanything.org/">testanything.org</a>.
 %
 % 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 ***
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.