Eliminates non-existing variable

Also some reflow, some additional comments, overall closes #2466

Author: JJ

doc/Type/Test.pod6

@@ -107,7 +107,8 @@ Defined as:
 
 The C<ok> function marks a test as passed if the given C<$value> evaluates to
 C<True>. The C<nok> function marks a test as passed if the given value evaluates
-to C<False>. Both functions accept an optional C<$description> of the test.
+to C<False>. Both functions accept an optional description of the test as second
+parameter.
 
     my $response; my $query; ...;
     ok  $response.success, 'HTTP response was successful';
@@ -130,7 +131,8 @@ Defined as:
     multi sub nok(Mu $cond, $desc = '')
 
 The C<nok> function marks a test as passed if the given value evaluates to
-C<False>. It also accepts an optional C<$description> of the test.
+C<False>. It also accepts an optional description of the test as second
+argument.
 
     my $response; my $query; ...;
     ok  $response.success, 'HTTP response was successful';
@@ -146,13 +148,13 @@ Defined as
 
 Marks a test as passed if C<$value> and C<$expected> compare positively with the
 L<eq operator|/routine/eq>, unless C<$expected> is a type object, in which case
-C<===> operator will be used instead; accepts an optional C<$description> of the
-test.
+C<===> operator will be used instead; accepts an optional description of the
+test as the last argument.
 
-B<NOTE:> C<eq> operator the C<is()> uses stringifies,
-which means C<is()> is not a good function for testing more complex things, such
-as lists: C<is (1, (2, (3,))), [1, 2, 3]> passes the test, even though the operands
-are vastly different. For those cases, use
+B<NOTE:> C<eq> operator the C<is()> uses stringifies, which means C<is()> is not
+a good function for testing more complex things, such as lists: C<is (1, (2,
+(3,))), [1, 2, 3]> passes the test, even though the operands are vastly
+different. For those cases, use
 L«C<is-deeply> routine|/language/testing#index-entry-is-deeply-is-deeply($value,_$expected,_$description?)»
 
     my $pdf-document; sub factorial($x) { ... }; ...;
@@ -176,7 +178,7 @@ Defined as:
     multi sub isnt(Mu $got, Mu:D $expected, $desc = '')
 
 Marks a test as passed if C<$value> and C<$expected> are B<not> equal using
-the same rules as C<is()>.  The function accepts an optional C<$description>
+the same rules as C<is()>.  The function accepts an optional description
 of the test.
 
     isnt pi, 3, 'The constant π is not equal to 3';
@@ -293,7 +295,7 @@ Defined as:
 Marks a test as passed if C<$value> and C<$expected> are equivalent, using the
 same semantics as the L<eqv operator|/routine/eqv>. This is the best way to
 check for equality of (deep) data structures. The function accepts an optional
-C<$description> of the test.
+description of the test as the last argument.
 
 =begin code
 use Test;
@@ -327,7 +329,7 @@ L«C<cmp-ok $got, 'eqv', $expected, $desc>|/language/testing#By_arbitrary_compar
     multi sub cmp-ok(Mu $got is raw, $op, Mu $expected is raw, $desc = '')
 
 Compares C<$value> and C<$expected> with the given C<$comparison> comparator and
-passes the test if the comparison yields a C<True> value. The C<$description>
+passes the test if the comparison yields a C<True> value. The description
 of the test is optional.
 
 The C<$comparison> comparator can be either a L<Callable> or
@@ -357,7 +359,8 @@ Defined as:
 
 Marks a test as passed if the given object C<$value> is, or inherits from, the
 given C<$expected-type>.  For convenience, types may also be specified as a
-string.  The function accepts an optional C<$description> of the test.
+string.  The function accepts an optional description of the test, which
+defaults to a string that describes the object.
 
     class Womble {}
     class GreatUncleBulgaria is Womble {}
@@ -373,7 +376,7 @@ Defined as:
     multi sub can-ok(Mu $var, Str $meth,$desc = "..." )
 
 Marks a test as passed if the given C<$variable> can run the given
-C<$method-name>.  The function accepts an optional C<$description>.  For
+C<$method-name>.  The function accepts an optional description.  For
 instance:
 
     class Womble {};
@@ -394,7 +397,7 @@ Defined as:
     multi sub does-ok(Mu $var, Mu $type, $desc = "...")
 
 Marks a test as passed if the given C<$variable> can do the given C<$role>.
-The function accepts an optional C<$description> of the test.
+The function accepts an optional description of the test.
 
     # create a Womble who can invent
     role Invent {
@@ -427,8 +430,8 @@ Use it this way:
     like 'foo', /fo/, 'foo looks like fo';
 
 Marks a test as passed if the C<$value>, when coerced to a string, matches the
-C<$expected-regex>.  The function accepts an optional C<$description> of the
-test.
+C<$expected-regex>.  The function accepts an optional description of the
+test with a default value printing the expected match.
 
 =head2 sub unlike
 
@@ -441,8 +444,8 @@ Used this way:
     unlike 'foo', /bar/, 'foo does not look like bar';
 
 Marks a test as passed if the C<$value>, when coerced to a string, does B<not>
-match the C<$expected-regex>.  The function accepts an optional C<$description>
-of the test.
+match the C<$expected-regex>.  The function accepts an optional description
+of the test, which defaults to printing the text that did not match.
 
 =head2 sub use-ok
 
@@ -462,7 +465,7 @@ Defined as:
 
 Marks a test as passed if the given C<$code> throws an exception.
 
-The function accepts an optional C<$description> of the test.
+The function accepts an optional description of the test.
 
 =begin code
 sub saruman(Bool :$ents-destroy-isengard) {
@@ -481,7 +484,7 @@ Defined as:
 Marks a test as passed if the given C<$code> B<does not> throw an
 exception.
 
-The function accepts an optional C<$description> of the test.
+The function accepts an optional description of the test.
 
 =begin code
 sub frodo(Bool :$destroys-ring) {
@@ -500,7 +503,7 @@ Defined as:
 Marks a test as passed if the given C<$string> throws an exception when
 C<eval>ed as code.
 
-The function accepts an optional C<$description> of the test.
+The function accepts an optional description of the test.
 
 =begin code
 eval-dies-ok q[my $joffrey = "nasty";
@@ -517,7 +520,7 @@ Defined as:
 Marks a test as passed if the given C<$string> B<does not> throw an
 exception when C<eval>ed as code.
 
-The function accepts an optional C<$description> of the test.
+The function accepts an optional description of the test.
 
 =begin code
 eval-lives-ok q[my $daenerys-burns = False;
@@ -532,20 +535,23 @@ Defined as:
     sub throws-like($code, $ex_type, $reason?, *%matcher)
 
 Marks a test as passed if the given C<$code> throws the specific exception
-C<$expected-exception>. The code C<$code> may be specified as something
-C<Callable> or as a string to be C<EVAL>ed. The exception may be specified
-as a type object or as a string containing its type name.
+expected exception type C<$ex_type>. The code C<$code> may be specified as
+something C<Callable> or as a string to be C<EVAL>ed. The exception may be
+specified as a type object or as a string containing its type name.
 
 If an exception was thrown, it will also try to match the matcher hash,
 where the key is the name of the method to be called on the exception, and
 the value is the value it should have to pass. For example:
 
 =begin code
-sub frodo(Bool :$destroys-ring) { fail "Oops. Frodo dies" unless $destroys-ring };
+sub frodo(Bool :$destroys-ring) {
+    fail "Oops. Frodo dies" unless $destroys-ring
+};
 throws-like { frodo }, Exception, message => /dies/;
 =end code
 
-The function accepts an optional C<$description> of the test.
+The function accepts an optional description of the test as the third
+positional argument.
 
 The routine makes L<Failures|/type/Failure> fatal. If you wish to avoid that,
 use L«C<no fatal> pragma|/language/pragmas#index-entry-fatal-fatal» and ensure
@@ -593,7 +599,7 @@ The C<subtest> function executes the given block, consisting of usually more
 than one test, possibly including a C<plan> or C<done-testing>, and counts as
 I<one> test in C<plan>, C<todo>, or C<skip> counts. It will pass the
 test only if B<all> tests in the block pass. The function accepts an
-optional C<$description> of the test.
+optional description of the subtest.
 
 =begin code
 class Womble {}
@@ -752,7 +758,7 @@ Defined as:
     multi sub pass($desc = '')
 
 The C<pass> function marks a test as passed. C<flunk> marks a test as
-B<not> passed. Both functions accept an optional test C<$description>.
+B<not> passed. Both functions accept an optional test description.
 
     pass "Actually, this test has passed";