Document Foo => 42 trap

Resolves #1721

Author: AlexDaniel

doc/Language/traps.pod6

@@ -533,6 +533,32 @@ If you are working with regexes, then there is no need to use C<.fc>
 and you can use C<:i> (C<:ignorecase>) adverb instead.
 
 
+=head1 Pairs
+
+=head2 Constants on LHS of pair notation
+
+Consider this code:
+
+=begin code
+enum Animals <Dog Cat>;
+my %h := :{ Dog => 42 };
+say %h{Dog}; # OUTPUT: «(Any)␤»
+=end code
+
+The C<:{ … }> syntax is used to create
+L<object hashes|/type/Hash#Non-string_keys_(object_hash)>. The
+intentions of someone who wrote that code were to create a hash with
+Enum objects as keys (and C<say %h{Dog}> attempts to get a value using
+the Enum object to perform the lookup). However, that's not how pair
+notation works.
+
+For exapmple, in C«Dog => 42» the key will be a C<Str>. That is, it
+doesn't matter if there is a constant, or an enumeration with the
+same name. The pair notation will always use the left-hand side as a
+string literal, as long as it looks like an identifier.
+
+To avoid this, use C«(Dog) => 42» or C«::Dog => 42».
+
 =head1 Operators
 
 Some operators commonly shared among other languages were repurposed in Perl 6 for other, more common, things: