Reduce variety of :skip-test explanations

taboege · taboege · commit ebaa8d8e5ea8 · 2019-05-04T22:22:28.000+02:00
This commit reduces the number of distinct reasons for :skip-test
from 48 to 31. Most of them are generic "needs filesystem access",
"needs ecosystem module", "illustrates error/trap" problems.
diff --git a/doc/Language/5to6-nutshell.pod6 b/doc/Language/5to6-nutshell.pod6
@@ -42,7 +42,7 @@ an embedded instance of the C<perl> interpreter to run Perl 5 code.
 
 This is as simple as:
 
-=for code :skip-test<Inline module not always present when testing>
+=for code :skip-test<needs ecosystem>
 # the :from<Perl5> makes Perl 6 load Inline::Perl5 first (if installed)
 # and then load the Scalar::Util module from Perl 5
 use Scalar::Util:from<Perl5> <looks_like_number>;
diff --git a/doc/Language/5to6-perlvar.pod6 b/doc/Language/5to6-perlvar.pod6
@@ -173,7 +173,7 @@ No longer exists in Perl 6.  Because each Repository is responsible for
 remembering which modules have been loaded already. You can get a list
 of all loaded modules (compilation units) like so:
 
-=for code :skip-test<missing module>
+=for code :skip-test<needs dummy module>
 use Test;
 use MyModule;
 say flat $*REPO.repo-chain.map(*.loaded); #-> (MyModule Test)
diff --git a/doc/Language/control.pod6 b/doc/Language/control.pod6
@@ -89,7 +89,7 @@ Class bodies behave like simple blocks for any top level expression; same goes
 to roles and other packages, like grammars (which are actually classes)
 or modules.
 
-=begin code :skip-test<Fails>
+=begin code :skip-test<dies deliberately>
 class C {
     say "I live";
     die "I will never live!"
diff --git a/doc/Language/experimental.pod6 b/doc/Language/experimental.pod6
@@ -61,7 +61,7 @@ Macro processing happens during parsing time. A macro generates an abstract
 syntax tree, which is grafted into the program syntax tree. C<quasi> is the
 routine that performs this task.
 
-=begin code :skip-test<need use experimental>
+=begin code :skip-test<needs experimental>
 macro does-nothing() {
     quasi {}
 };
@@ -72,7 +72,7 @@ X<|quasi (macros)>
 Macros are a kind of routine, so they can take arguments in exactly the same
 way, and act also in almost the same way.
 
-=begin code :skip-test<need use experimental>
+=begin code :skip-test<needs experimental>
 macro is-mighty( $who ) {
     quasi { "$who is mighty!"}
 };
@@ -86,7 +86,7 @@ including the quotes. Please note that we can also eliminate the parentheses for
 a macro call, following the same rules as a routine. You can use the unquoting
 construct C<{{{}}}> to get rid of this kind of thing:
 
-=begin code :skip-test<need use experimental>
+=begin code :skip-test<needs experimental>
 macro is-mighty( $who ) {
     quasi { {{{$who}}} ~ " is mighty!"}
 };
@@ -96,7 +96,7 @@ say is-mighty "Freija";  # OUTPUT: «Freija is mighty!␤»
 Since macro expansion happens at parse time, care must be taken when using
 external variables in them:
 
-=begin code :skip-test<need use experimental>
+=begin code :skip-test<needs experimental>
 use experimental :macros;
 my $called;
 macro called() {
@@ -136,7 +136,7 @@ It can be used when heavy calculations are involved, as in this sample that uses
 L<amicable numbers|https://perl6advent.wordpress.com/2018/12/25/calling-numbers-names/#more-7528>,
 taken from the 2018 Advent Calendar:
 
-=begin code :skip-test<Uses experimental>
+=begin code :skip-test<needs experimental>
 use experimental :cached;
 
 sub aliquot-parts( $number ) is cached {
diff --git a/doc/Language/functions.pod6 b/doc/Language/functions.pod6
@@ -362,7 +362,7 @@ arguments. Consider this basic example:
     congratulate('being a cool number', 'Fred');     # OK
     congratulate('being a cool number', 'Fred', 42); # OK
 
-=for code :skip-test<Proto match error>
+=for code :skip-test<illustrates error>
 congratulate('being a cool number', 42);         # Proto match error
 
 The proto insists that all C<multi congratulate> subs conform to the basic
@@ -395,7 +395,7 @@ with. Parameter defaults and type coercions will work but are not passed on.
 proto mistake-proto(Str() $str, Int $number = 42) {*}
 multi mistake-proto($str, $number) { say $str.^name }
 mistake-proto(7, 42);  # OUTPUT: «Int␤» -- not passed on
-=for code :skip-test<compilation error>
+=for code :skip-test<illustrates error>
 mistake-proto('test'); # fails -- not passed on
 
 =head2 X<only|declarator>
diff --git a/doc/Language/glossary.pod6 b/doc/Language/glossary.pod6
@@ -131,7 +131,7 @@ that name:
 # anonymous, but knows its own name
 my $s = anon sub triple($x) { 3 * $x }
 say $s.name;        # OUTPUT: «triple␤»
-=for code :skip-test<error>
+=for code :skip-test<illustrates error>
 say triple(42);     # OUTPUT: «Undeclared routine: triple␤»
 
 X<|API>
diff --git a/doc/Language/grammar_tutorial.pod6 b/doc/Language/grammar_tutorial.pod6
@@ -322,7 +322,7 @@ Will output exactly the same as the code above.  Symptomatic of the difference
 between Classes and Roles, a conflict like defining C<token quote> twice
 using Role composition will result in an error:
 
-=begin code :skip-test<compilation error>
+=begin code :skip-test<compile-time error>
 grammar Quoted-Quotes does Letters does Quote-Quotes does Quote-Other { ... }
 # OUTPUT: ... Error while compiling ... Method 'quote' must be resolved ...
 =end code
diff --git a/doc/Language/js-nutshell.pod6 b/doc/Language/js-nutshell.pod6
@@ -710,7 +710,7 @@ In Perl 6, variables can be typed by placing the type between the declarator
 match the variable's type will throw either a compile-time or runtime error,
 depending on how the value is evaluated:
 
-=begin code :skip-test<deliberate compile-time error>
+=begin code :skip-test<compile-time error>
 enum Name <Phoebe Daniel Joe>;
 my Str $name = 'Phoebe';
 $name = Phoebe; # Throws a compile-time error
diff --git a/doc/Language/list.pod6 b/doc/Language/list.pod6
@@ -570,7 +570,7 @@ However, the following calls will all fail, due to passing an untyped array,
 even if the array just happens to contain Int values at the point it is
 passed:
 
-    =begin code :skip-test<compilation errors>
+    =begin code :skip-test<illustrates error>
     my @c = 1, 3, 5;
     say mean(@c);                       # Fails, passing untyped Array
     say mean([1, 3, 5]);                # Same
diff --git a/doc/Language/math.pod6 b/doc/Language/math.pod6
@@ -279,7 +279,7 @@ parameter.
 How can we translate that into Perl 6? Well Math::Model brings some help
 with a very understandable way to do that--let's see it:
 
-=begin code :skip-test<can't use>
+=begin code :skip-test<needs ecosystem>
 use Math::Model;
 
 my $m = Math::Model.new(
@@ -394,7 +394,7 @@ where the constant g defines the growth rate and k is the carrying
  capacity.
 Modifying the above code we can simulate its behavior in time:
 
-=begin code :skip-test<can't use>
+=begin code :skip-test<needs ecosystem>
 use Math::Model;
 
 my $m = Math::Model.new(
@@ -444,7 +444,7 @@ I<critical point>.
 
 Our code would be:
 
-=begin code :skip-test<can't use>
+=begin code :skip-test<needs ecosystem>
 use Math::Model;
 
 my $m = Math::Model.new(
@@ -484,7 +484,7 @@ I<dx/dt=r*x*(1-x/k)*(x/a)**n>, with n>0
 
 Our code would be:
 
-=begin code :skip-test<can't use>
+=begin code :skip-test<needs ecosystem>
 use Math::Model;
 
 my $m = Math::Model.new(
diff --git a/doc/Language/module-packages.pod6 b/doc/Language/module-packages.pod6
@@ -57,7 +57,7 @@ scoped it is aliased in the module's symbol table. Finally,
 C<friendly-greeting> is marked for export; it will be registered in the
 I<caller's> symbol table when the module is imported:
 
-=begin code :skip-test<can't import>
+=begin code :skip-test<needs dummy module>
 import M;               # import the module
 say M::loud-greeting;   # OUTPUT: «GREETINGS, CAMELIA!␤»
 say friendly-greeting;  # OUTPUT: «Greetings, friend!␤»
@@ -75,7 +75,7 @@ using, it needs to declare one with C<module> as documented above.
 For example, by placing module C<M> inside C<Foo.pm6>, we can load
 and use the module as follows:
 
-=begin code :skip-test<filesystem related>
+=begin code :skip-test<needs dummy module>
 use Foo;                # find Foo.pm6, run need followed by import
 say M::loud-greeting;   # OUTPUT: «GREETINGS, CAMELIA!␤»
 say friendly-greeting;  # OUTPUT: «Greetings, friend!␤»
@@ -104,7 +104,7 @@ module Foo {
 which can be used more consistently by the caller (note the
 relationship between the C<use Foo> and C<Foo::>):
 
-=begin code :skip-test<filesystem related>
+=begin code :skip-test<needs dummy module>
 use Foo;
 say Foo::loud-greeting;  # OUTPUT: «GREETINGS, CAMELIA!␤»
 say friendly-greeting;   # OUTPUT: «Greetings, friend!␤»
@@ -153,15 +153,15 @@ sub friendly-greeting is export  { greeting('friend')           }
 
 As a reminder, here's how we used C<Foo.pm6> before,
 
-=begin code :skip-test<filesystem related>
+=begin code :skip-test<needs dummy module>
 use Foo;
 say Foo::loud-greeting;  # OUTPUT: «GREETINGS, CAMELIA!␤»
 say friendly-greeting;   # OUTPUT: «Greetings, friend!␤»
 =end code
 
 and here's how we use C<Bar.pm6>,
 
-=begin code :skip-test<filesystem related>
+=begin code :skip-test<needs dummy module>
 use Bar;
 say loud-greeting;       # OUTPUT: «GREETINGS FROM BAR, CAMELIA!␤»
 say friendly-greeting;   # OUTPUT: «Greetings from Bar, friend!␤»
@@ -188,7 +188,7 @@ This creates a lexical alias, hiding the C<say> builtin I<inside>
 C<Bar.pm6> but leaving the caller's C<say> unchanged. Consequently,
 the following call to C<say> still works as expected:
 
-=begin code :skip-test<filesystem related>
+=begin code :skip-test<needs dummy module>
 use Bar;
 say 'Carry on, carry on...';  # OUTPUT: «Carry on, carry on...␤»
 =end code
diff --git a/doc/Language/nativecall.pod6 b/doc/Language/nativecall.pod6
@@ -672,7 +672,7 @@ to be prepended with "lib" and appended with ".so" (or just appended with
 ".dll" on Windows), and will be searched for in the paths in the
 LD_LIBRARY_PATH (PATH on Windows) environment variable.
 
-=begin code :skip-test<don't have library>
+=begin code :skip-test<external dependency>
 use NativeCall;
 constant LIBMYSQL = 'mysqlclient';
 constant LIBFOO = '/usr/lib/libfoo.so.1';
diff --git a/doc/Language/pragmas.pod6 b/doc/Language/pragmas.pod6
@@ -144,7 +144,7 @@ Allow for some other language constructs that were deemed to be a trap that
 warranted a warning and/or an error in normal Perl 6 programming.  Currently,
 C<Perl5> and C<C++> are allowed.
 
-=begin code :skip-test<compilation error>
+=begin code :skip-test<compile-time error>
 sub abs() { say "foo" }
 abs;
 # Unsupported use of bare "abs"; in Perl 6 please use .abs if you meant
diff --git a/doc/Language/rb-nutshell.pod6 b/doc/Language/rb-nutshell.pod6
@@ -71,7 +71,7 @@ coding styles:
 =begin item
 I<No space allowed before the opening parenthesis of an argument list.>
 
-=begin code :skip-test<error>
+=begin code :skip-test<illustrates error>
 foo (3, 4, 1); # Not right in Ruby or Perl 6 (in Perl 6 this would
                # try to pass a single argument of type List to foo)
 =end code
@@ -1091,7 +1091,7 @@ sub baz($z) { say "baz $z" }
 To use this module, simply C<use Bar> and the functions C<foo> and C<bar>
 will be available:
 
-=for code :skip-test<can't use>
+=for code :skip-test<needs dummy module>
 use Bar;
 foo(1);    #=> "foo 1"
 bar(2);    #=> "bar 2"
@@ -1100,7 +1100,7 @@ If you try to use C<baz> an "Undeclared routine" error is raised at compile time
 
 Some modules allow for selectively importing functions, which would look like:
 
-=begin code :skip-test<can't use>
+=begin code :skip-test<needs dummy module>
 use Bar <foo>; # Import only foo
 foo(1);        #=> "foo 1"
 bar(2);        # Error!
diff --git a/doc/Language/syntax.pod6 b/doc/Language/syntax.pod6
@@ -311,7 +311,7 @@ or C<[' ']> which quotes one or more arbitrary characters C<value>.N<Starting
 with Perl 6 language version 6.d, colon pairs with C<sym> as the C<key> (e.g.
 C«:sym<foo>») are reserved for possible future use.>
 
-=begin code :skip-test<Identifiers good and bad>
+=begin code :skip-test<partly bad identifiers>
 # exemplary valid extended identifiers:
 postfix:<²>               # the official long name of the operator in $x²
 WOW:That'sAwesome
@@ -361,7 +361,7 @@ say $a:b<c>:d<e>;               # OUTPUT: «100␤», NOT: «200␤»
 An exception to this rule is I<module versioning>; so these identifiers
 effectively name the same module:
 
-=begin code :skip-test<fake modules>
+=begin code :skip-test<needs dummy module>
 use ThatModule:auth<Somebody>:ver<2.7.18.28.18>
 use ThatModule:ver<2.7.18.28.18>:auth<Somebody>
 =end code
diff --git a/doc/Language/terms.pod6 b/doc/Language/terms.pod6
@@ -251,7 +251,7 @@ available. Auto-coercion on %-sigiled constants requires 6.d>
 An optional type constraint can be used, in which case the use
 of scope declarator is required:
 
-=begin code :skip-test<showcasing deliberate syntax error>
+=begin code :skip-test<illustrates error>
 # !!WRONG!! missing scope declarator before type:
 Int constant bar = 42;
 
@@ -263,7 +263,7 @@ Unlike L<variables|/language/variables>, you cannot parameterize C<@>-,
 C<%>-, and C<&>-sigiled constants by specifying the parameterization
 type in the declarator itself:
 
-    =begin code :skip-test<showcasing deliberate compile-time error>
+    =begin code :skip-test<illustrates error>
     # !!WRONG!! cannot parameterize @-sigiled constant with Int
     our Int constant @foo = 42;
 
diff --git a/doc/Type/IO/Handle.pod6 b/doc/Type/IO/Handle.pod6
@@ -949,7 +949,7 @@ to work with textual read/write methods and doesn't use the standard C<.open>
 method, be sure to call C<.encoding> method in your custom handle to get
 decoder/encoder properly set up:
 
-=begin code :skip-test<uses ecosystem modules>
+=begin code :skip-test<needs ecosystem>
 class IO::URL is IO::Handle {
     has $.URL is required;
     has Buf $!content;
