Make examples compile, improve signature catching part of extract-examples script.

Author: Altai-man

doc/Type/Exception.pod6

@@ -28,51 +28,52 @@ Defined as:
 
     method message(Exception:D:) returns Str:D
 
-Usage:
-
-    EXCEPTION.message
-
 This is a stub that must be overwritten by subclasses, and should
 return the exception message.
 
 Special care should be taken that this method does not produce
 an exception itself.
 
+    try die "Something bad happend";
+    if ($!) {
+        say $!.message; # Something bad happened.
+    }
+
 =head2 method backtrace
 
 Defined as:
 
     method backtrace(Exception:D:) returns Backtrace:D
 
-Usage:
-
-    EXCEPTION.backtrace
-
 Returns the backtrace associated with the exception. Only makes sense
 on exceptions that have been thrown at least once.
 
+    try die "Something bad happend";
+    if ($!) {
+        say $!.backtrace;
+    }
+
 =head2 method throw
 
 Defined as:
 
     method throw(Exception:D:)
 
-Usage:
-
-    EXCEPTION.throw
-
 Throws the exception.
 
-=head2 method resume
+    my $exception = X::AdHoc.new; # Totally fine
+    try $exception.throw;             # Throws
+    if ($!) { #`( some handling ) };                   # Suppress the exception in a
 
-Resumes control flow where C<.throw> left it when handled in a C<CATCH> block.
+=head2 method resume
 
 Defined as:
 
     method resume(Exception:D:)
 
-Usage:
+Resumes control flow where C<.throw> left it when handled in a C<CATCH> block.
 
+    # For example, resume control flow for any exception
     CATCH { default { .resume } }
 
 =head2 method rethrow
@@ -81,27 +82,23 @@ Defined as:
 
     method rethrow(Exception:D:)
 
-Usage:
-
-    EXCEPTION.rethrow
-
 Rethrows an exception that has already been thrown at least once.
 This is different from C<throw> in that it preserves the original
 backtrace.
 
+    my $e = X::AdHoc.new(payload => "Bad situation");
+    sub f() { die 'Bad' };
+    sub g() { try f; CATCH { default { .rethrow } } };
+    g;
+    CATCH { default { say .backtrace.full } };
+
 =head2 method fail
 
 Defined as:
 
-    sub    fail(*@text)
-    sub    fail(Exception $e)
-    method fail(Exception:D $e:)
-
-Usage:
-
-    fail(TEXT)
-    fail(EXCEPTION)
-    EXCEPTION.fail
+    multi sub    fail(*@text)
+    multi sub    fail(Exception $e)
+    multi method fail(Exception:D $e:)
 
 Exits the calling C<Routine> and returns a L<Failure> object wrapping the
 exception C<$e> - or, for the C<*@text> form, an L<X::AdHoc> exception
@@ -120,41 +117,36 @@ Defined as:
 
     multi method gist(Exception:D:)
 
-Usage:
-
-    EXCEPTION.gist
-
 Returns whatever the exception printer should produce for this exception.
 The default implementation returns message and backtrace separated by
 a newline.
 
+    my $e = X::AdHoc.new(payload => "This exception is pretty bad");
+    try $e.throw;
+    if ($!) { say $!.gist; };
+    # OUTPUT: «This exception is pretty bad
+    #   in block <unit> at <unknown file> line 1␤»
+
 =head2 sub die
 
 Defined as:
 
     multi sub die(*@message)
-    multi sub die(Exception:D $e:)
-    method    die(Exception:D $e:)
-
-Usage:
-
-    die(MESSAGE)
-    die(EXCEPTION)
-    EXCEPTION.die
+    multi sub die(Exception:D $e)
+    method    die(Exception:D $e)
 
 Throws a fatal C<Exception>. The default exception handler prints each
 element of the list to C<$*ERR> (STDERR).
 
+=for code :skip-test
+die "Important reason";
+
 =head2 sub warn
 
 Defined as:
 
     multi sub warn(*@message)
 
-Usage:
-
-    warn(MESSAGE)
-
 Throws a resumable warning exception, which is considered a control
 exception, and hence is invisible to most normal exception handlers.  The
 outermost control handler will print the warning to C<$*ERR>. After printing
@@ -167,6 +159,8 @@ To simply print to C<$*ERR>, please use C<note> instead.  C<warn> should be
 reserved for use in threatening situations when you don't quite want to
 throw an exception.
 
+    warn "Warning message";
+
 =end pod
 
 # vim: expandtab shiftwidth=4 ft=perl6

doc/Type/Grammar.pod6

@@ -29,11 +29,7 @@ More L<documentation on grammars|/language/grammars> is available.
 
 Defined as:
 
-    method parse($target, :$rule = 'TOP',  Capture() :$args = \(), Mu :$actions = Mu, *%opt) {
-
-Usage:
-
-    GRAMMAR.parse(TARGET, RULE?, ARGS?, ACTIONS?, OPTIONS?)
+    method parse($target, :$rule = 'TOP',  Capture() :$args = \(), Mu :$actions = Mu, *%opt)
 
 Parses the C<$target> (which will be coerced to L<Str|/type/Str> if it isn't
 one), using C<$rule> as the starting rule. Additional C<$args> will be given
@@ -84,35 +80,32 @@ failure.
 
 This outputs:
 
-    ｢Year,Make,Model,Length
-    1997,Ford,E350,2.34
-    2000,Mercury,Cougar,2.38
-    ｣
-     line => ｢Year,Make,Model,Length｣
-      value => ｢Year｣
-      value => ｢Make｣
-      value => ｢Model｣
-      value => ｢Length｣
-     line => ｢1997,Ford,E350,2.34｣
-      value => ｢1997｣
-      value => ｢Ford｣
-      value => ｢E350｣
-      value => ｢2.34｣
-     line => ｢2000,Mercury,Cougar,2.38 ｣
-      value => ｢2000｣
-      value => ｢Mercury｣
-      value => ｢Cougar｣
-      value => ｢2.38 ｣
+=for code :skip-test
+｢Year,Make,Model,Length
+1997,Ford,E350,2.34
+2000,Mercury,Cougar,2.38
+｣
+ line => ｢Year,Make,Model,Length｣
+  value => ｢Year｣
+  value => ｢Make｣
+  value => ｢Model｣
+  value => ｢Length｣
+ line => ｢1997,Ford,E350,2.34｣
+  value => ｢1997｣
+  value => ｢Ford｣
+  value => ｢E350｣
+  value => ｢2.34｣
+ line => ｢2000,Mercury,Cougar,2.38 ｣
+  value => ｢2000｣
+  value => ｢Mercury｣
+  value => ｢Cougar｣
+  value => ｢2.38 ｣
 
 =head2 method subparse
 
 Defined as:
 
-    method subparse($target, :$rule = 'TOP', Capture() :$args = \(),  Mu :$actions = Mu, *%opt) {
-
-Usage:
-
-    GRAMMAR.subparse(TARGET, RULE?, ARGS?, ACTIONS?, OPTIONS?)
+    method subparse($target, :$rule = 'TOP', Capture() :$args = \(),  Mu :$actions = Mu, *%opt)
 
 Does exactly the same as L<method parse|/routine/parse>, except that cursor
 doesn't have to reach the end of the string to succeed. (That is, it doesn't
@@ -129,13 +122,15 @@ have to match the whole string).
 
 Defined as:
 
-    method parsefile(Str(Cool) $filename, :$enc, *%opts) {
-
-Usage:
-
-    GRAMMAR.parsefile(FILE, OPTIONS?)
+    method parsefile(Str(Cool) $filename, :$enc, *%opts)
 
 Reads file C<$filename>, and parses it. All named arguments are passed on to
 L<method parse|/routine/parse>.
 
+=for code :skip-test
+grammar A {
+    token TOP { a+ };
+}
+A.parsefile('my-good-file', 'UTF-8');
+
 =end pod

doc/Type/IntStr.pod6

@@ -4,7 +4,7 @@
 
 =SUBTITLE Dual Value Integer and String
 
-    class IntStr is Int is Str
+    class IntStr is Int is Str { }
 
 The dual value types (often referred to as L<allomorphs|/language/glossary#Allomorph>)
 allow for the representation of a value as both a string and a numeric type, typically

doc/Type/Junction.pod6

@@ -52,6 +52,8 @@ use a L<Set> or a related type instead.
 
 Usage examples:
 
+    my @list = <1 2 "Great">;
+    @list.append(True).append(False);
     my @bool_or_int = grep Bool|Int, @list;
 
     sub is_prime(Int $x) returns Bool {
@@ -68,10 +70,11 @@ Special care should be taken when using C<all> with arguments that may
 produce an empty list:
 
     my @a = ();
-    so all(@a) # True, because there are 0 False's
+    say so all(@a) # True, because there are 0 False's
 
 To express "all, but at least one", you can use C<@a && all(@a)>
 
+    my @a = ();
     say so @a && all(@a);   # False
 
 Negated operators are special-cased when it comes to autothreading.

doc/Type/Rat.pod6

@@ -4,7 +4,7 @@
 
 =SUBTITLE Rational number (limited-precision)
 
-    class Rat is Cool does Rational[Int, UInt64] { ... }
+    class Rat is Cool does Rational[Int, UInt64] { }
 
 C<Rat> objects store rational numbers as a pair of a numerator and
 denominator. Number literals with a dot but without exponent produce

doc/Type/Rational.pod6

@@ -16,19 +16,22 @@ Built into Perl 6 are L<Rat> and L<FatRat>, which both do the C<Rational> role.
 
 =head2 method new
 
-    method new(NuT:D $numerator, DeT:D $denominator) returns Rational:D
+=for code :skip-test
+method new(NuT:D: $numerator, DeT:D: $denominator) returns Rational:D
 
 Creates a new rational object from numerator and denominator.
 
 =head2 method numerator
 
-    method numerator(Rational:D:) returns NuT:D
+=for code :skip-test
+method numerator(Rational:D:) returns NuT:D
 
 Returns the numerator.
 
 =head2 method denominator
 
-    method denominator(Rational:D:) returns DeT:D
+=for code :skip-test
+method denominator(Rational:D:) returns DeT:D
 
 Returns the denominator.
 

doc/Type/Real.pod6

@@ -64,7 +64,7 @@ Rounds the number towards zero.
 Converts the number to a string, using C<$base> as base. For C<$base> larger
 than ten, capital Latin letters are used.
 
-    255.base(16)            # 'FF'
+    255.base(16);            # 'FF'
 
 The optional C<$digits> argument asks for that many digits of fraction
 (which may not be negative).  If omitted, a reasonable default is chosen
@@ -79,7 +79,7 @@ The final digit produced is always rounded.
 To convert a string to a number use the C<:16($string)> notation where 16 is
 the base:
 
-    say :16("FF")           # 255
-    say :23("FF")           # 360
+    say :16("FF");           # 255
+    say :23("FF");           # 360
 
 =end pod

doc/Type/Semaphore.pod6

@@ -17,16 +17,18 @@ printer becomes available.
 
     method BUILD( Int:D :$nbr-printers ) {
       for ^$nbr-printers -> $pc {
-        $!printers[$pc] = { :name{"printer-$pc"}, ... };
+        $!printers[$pc] = { :name{"printer-$pc"} };
       }
 
       $!print-control .= new($nbr-printers);
     }
 
+    method find-available-printer-and-print-it($job) { say "Is printed!"; }
+
     method print( $print-job ) {
       $!print-control.acquire;
 
-      find-available-printer-and-print-it($job);
+      self.find-available-printer-and-print-it($print-job);
 
       $!print-control.release;
     }

doc/Type/Set.pod6

@@ -24,6 +24,7 @@ C<Set>s can be treated as object hashes using the C<{ }> postcircumfix operator,
 which returns the value C<True> for keys that are elements of the set, and
 C<False> for keys that aren't:
 
+    my $fruits = set <peach apple orange apple apple>;
     say $fruits<apple>;  # True
     say $fruits<kiwi>;   # False
 

doc/Type/SetHash.pod6

@@ -26,6 +26,8 @@ and C<False> for keys that aren't. Assigning a value that boolifies to C<True>
 or C<False>, respectively, can be used to add or remove a set element:
 
 =begin code
+my $fruits = <peach apple orange apple apple>.SetHash;
+
 say $fruits<apple>;     # True
 say $fruits<kiwi>;      # False