Clarify is()'s usecases

Author: zoffixznet

doc/Language/testing.pod6

@@ -215,15 +215,17 @@ X<|is,testing>
 =item is($value, $expected, $description?)
 
 Marks a test as passed if C<$value> and C<$expected> compare positively with
-the L<eq operator|/routine/eq>. The function accepts an optional
-C<$description> of the test.
+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.
+
+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?)»
 
     is $pdf-document.author, "Joe", 'Retrieving the author field';
     is factorial(6),         720,   'Factorial - small integer';
-
-As a special case, if C<$expected> is a type object, the comparison uses the
-C<===> operator instead:
-
     my Int $a;
     is $a, Int, 'The variable $a is an unassigned Int';