Merge pull request #564 from tbrowder/test-skip

add an example output for 'todo'; add notes about 'skip' and 'skip-te…

Author: jonathanstowe

doc/Language/testing.pod

@@ -410,6 +410,15 @@ only one test will be marked TODO.
     is my-custom-pi(), pi, 'my-custom-pi'; # Run the test, but don't report
                                            # failure in test harness.
 
+The result from the test code above will be something like:
+
+    not ok 1 - my-custom-pi# TODO not yet precise enough
+    
+    # Failed test 'my-custom-pi'
+    # at test-todo.t line 7
+    # expected: '3.14159265358979'
+    #      got: '3'
+
 =item X<skip($reason, $count = 1)|skip>
 
 Skip C<$count> tests, giving a C<$reason> as to why.  By default only one
@@ -426,6 +435,9 @@ else {
 }
 =end code
 
+Note that if you mark a test as skipped, you must also prevent that
+test from running.
+
 =item X<skip-rest($reason?)|skip-rest>
 
 Skip the remaining tests.  If the remainder of the tests in the test file
@@ -446,7 +458,10 @@ ok womble();
 Note that C<skip-rest> requires a C<plan> to be set, otherwise the
 C<skip-rest> call will throw an error. If no plan was set, you can use
 C<done> to indicate the end of the test run (though of course the test
-summary will not count skipped tests).
+summary will not count skipped tests).  Note also the C<exit> is
+required in the example to prevent the skipped tests from running.
+Alternatively, you could enclose the remaining tests in an C<else>
+branch.
 
 =head1 Manual control