doc trap of ~~ in conjunction with .method-name

Author: gfldex

doc/Language/traps.pod6

@@ -279,6 +279,26 @@ starting string:
     say join ", ", ("az", *.succ ... "bc")
     az, ba, bb, bc
 
+The smart match operator C<~~> does set the topic C<$_> to its LHS. In
+conjunction with implicit method call on the topic this can lead to surprising
+results.
+
+    my &method = { note $_; $_ };
+    $_ = 'object';
+    say .&method;
+    # OUTPUT«object␤object␤»
+    say 'topic' ~~ .&method;
+    # OUTPUT«topic␤True␤»
+
+In many cases flipping the method call to the LHS will work.
+
+    my &method = { note $_; $_ };
+    $_ = 'object';
+    say .&method;
+    # OUTPUT«object␤object␤»
+    say .&method ~~ 'topic';
+    # OUTPUT«object␤True␤»
+
 =head1 Common Precedence Mistakes
 
 =head2 Adverbs and Precedence