document more exception classes

Author: moritz

lib/X/Attribute/Undeclared.pod

@@ -0,0 +1,29 @@
+=begin pod
+
+=title class X::Attribute::Undeclared
+
+    class X::Attribute::Undeclared is X::Undeclared { }
+
+Thrown when code refers to an attribute that has not been declared.
+
+For example the code
+
+    class A { method m { $!notthere } }
+
+Produces the error
+
+    Attribute $!notthere not declared in class A
+
+=head1 Methods
+
+=head2 package-kind
+
+Returns the kind of package the attribute was used in (for example C<class>,
+C<grammar>)
+
+=head2 package-name
+
+Returns the name of the package in which the offensive attribute reference
+was performed.
+
+=end pod

lib/X/Parameter/Default.pod

@@ -0,0 +1,40 @@
+=begin pod
+
+=TITLE class X::Parameter::Default
+
+    class X::Parameter::Default does X::Comp { }
+
+Compile-time error thrown when a parameter in a signature has default value,
+but isn't allowed to have one. That is the case with slurpy parameters
+(because a slurpy always binds successfully, even to zero arguments)
+and with mandatory parameters.
+
+Example:
+
+    sub f($x! = 3) { }
+
+Produces
+
+    ===SORRY!===
+    Cannot put default on required parameter $x
+
+And
+
+    sub f(*@ = 3) { }
+
+produces
+
+    Cannot put default on anonymous slurpy parameter
+
+=head1 Methods
+
+=head2 how
+
+Returns a string describing how the parameter is qualified that makes
+it disallow default values, for example C<"slurpy"> or C<"mandatory">.
+
+=head2 parameter
+
+Returns the parameter name
+
+=end pod

lib/X/Parameter/MultipleTypeConstraints.pod

@@ -0,0 +1,24 @@
+=begin pod
+
+=TITLE X::Parameter::MultipleTypeConstraints
+
+    class X::Parameter::MultipleTypeConstraints does X::Comp { }
+
+Compile time error thrown when a parameter has multiple type constraints.
+This is not allowed in Perl 6.0.
+
+Example:
+
+    sub f(Cool Real $x) { }
+
+produces
+
+    Parameter $x may onle have one prefix type constraint
+ 
+=head1 Methods
+
+=head2 parameter
+
+Returns the name of the offensive parameter.
+
+=end pod

lib/X/Parameter/Placeholder.pod

@@ -0,0 +1,34 @@
+=begin pod
+
+=TITLE class X::Parameter::Placeholder
+
+    class X::Parameter::Placeholder does X::Comp
+
+Thrown when a placeholder parameter is used inside a signature where
+a normal parameter is expected. The reason is often that a named parameter
+C<:$param> was misspelled as C<$:param>.
+
+For example
+
+    sub f($:param) { }
+
+produces
+
+    ===SORRY!===
+    In signature parameter, placeholder variables like $:param are illegal
+    you probably meant a named parameter: ':$param'
+
+=head1 Methods
+
+=head2 parameter
+
+The text of the offensive parameter declaration (C<$:param> in the example
+above).
+
+=head2 right
+
+Suggestion on how to write the parameter declaration instead (C<:$param> in
+the example above).
+
+
+=end pod

lib/X/Parameter/Twigil.pod

@@ -0,0 +1,29 @@
+=begin pod
+
+=TITLE class X::Parameter::Twigil
+
+    class X::Parameter::Twigil does X::Comp
+
+Thrown when a parameter in a signature has a twigil that it may not have.
+Only C<!>, C<.> and C<*> as twigils are allowed.
+
+Example:
+
+    sub f($=foo) { }
+
+produces
+
+    ===SORRY!===
+    In signature parameter $=foo, it is illegal to use the = twigil
+
+=head1 Methods
+
+=head2 parameter
+
+The name of the offensive parameter (C<$=foo> in the example above)
+
+=head2 twigil
+
+The illegally used twigil.
+
+=end pod

lib/X/Parameter/WrongOrder.pod

@@ -0,0 +1,36 @@
+=begin pod
+
+=TITLE X::Parameter::WrongOrder
+
+    class X::Parameter::WrongOrder does X::Comp
+
+Compile time error that is thrown when parameters in a signature in the wrong
+order (for example if an optional parameter comes before a mandatory
+parameter).
+
+For example
+
+    sub f($a?, $b) { }
+
+produces
+
+    Cannot put required parameter $b after optional parameters
+
+=head1 Methods
+
+=head2 misplaced
+
+Returns the kind of misplaced parameter (for example C<"mandatory">,
+C<"positional">).
+
+=head2 parameter
+
+Returns the name of the (first) misplaced parameter
+
+=head2 after
+
+Returns a string describing other parameters after which the current parameter
+was illegally placed (for example C<"variadic">, C<"positional"> or
+C<"optional">).
+
+=end pod

lib/X/Phaser/Multiple.pod

@@ -0,0 +1,25 @@
+=begin pod
+
+=TITLE class X::Phaser::Multiple
+
+    class X::Phaser::Multiple does X::Comp
+
+Thrown when multiple phasers of the same type occur in a block, but only one
+is allowed (for example C<CATCH> or C<CONTROL>).
+
+Example
+
+    CATCH { }; CATCH { }
+
+Produces
+
+    ===SORRY!===
+    Only one CATCH block is allowed
+
+=head1 Methods
+
+=head2 block
+
+Returns the name of the phaser that occured more than once.
+
+=end pod

lib/X/Placeholder/Mainline.pod

@@ -15,4 +15,11 @@ Produces the error message
 
     Cannot use placeholder parameter $^x in the mainline
 
+Note that this error can also occur when you think something is a block,
+but it really is a L<< postcircumfix:<{ }> >>, for example
+
+    my %h;
+    say %h{ $^x };
+    #     ^^^^^^^  not a block, so $^x is part of the mainline
+
 =end pod

lib/X/Redeclaration.pod

@@ -0,0 +1,51 @@
+=begin pod
+
+=TITLE class X::Redeclaration
+
+    class X::Redeclaration does X::Comp { }
+
+Thrown when a symbol (variable, routine, type, paramater, ...) is redeclared.
+Note that redeclarations are generally fine in an inner scope, but if the
+redeclaration appears in the same scope as the original declaration,
+it usually indicates an error and is treated as one.
+
+Examples
+
+    my $x; my $x
+
+    ===SORRY!===
+    Redeclaration of symbol $x
+
+    sub f() { }
+    sub f() { }
+    ===SORRY!===
+    Redeclaration of routine f
+
+But those are fine
+
+    my $x;
+    sub f() {
+        my $x;          # not a redeclaration,
+                        # because it's in an inner scope
+        sub f() { };    # same
+    }
+
+
+=head1 Methods
+
+=head2 symbol
+
+Returns the name of the symbol that was redeclared.
+
+=head1 what
+
+Returns the kind of symbol that was redeclared. Usually C<symbol>, but can
+also be C<routine>, C<type> etc.
+
+=head1 postfix
+
+Returns a string that is attached to the end of the error message. It
+usually explains the particular problem in more detail, or suggests
+way to fix the problem.
+
+=end pod

lib/X/Undeclared.pod

@@ -0,0 +1,37 @@
+=begin pod
+
+=TITLE class X::Undeclared
+
+    class X::Undeclared does X::Comp
+
+Thrown when the compiler encounters a symbol that has not been declared,
+but needs to be.
+
+Example
+
+    $x
+
+    ===SORRY!===
+    Variable $x is not declared
+
+=head1 Methods
+
+=head2 symbol
+
+Returns the name of the undeclared symbol
+
+=head2 what
+
+Returns the kind of symbol that was not declared (for example variable,
+type, routine).
+
+Since The symbol wasn't declared, the compiler sometimes has to guess
+(or rather disambiguate) what kind of symbol it encounter that wasn't
+declared. For example if you write
+
+    say a
+
+Then the disambiguation defaults to reporting a missing subroutine, even
+though declaring a C<constant a = 'a'> would also make the error go away.
+
+=end pod