better document smart match overloading

(cherry picked from commit 0de1c906c34397b53c088e443cd0325d9c209649)

2 files changed, 37 insertions, 2 deletions

diff --git a/lib/overload.pm b/lib/overload.pm
index 0cb4771845..f83191b5cd 100644
--- a/lib/overload.pm
+++ b/lib/overload.pm
@@ -427,6 +427,31 @@ The key C<"~~"> allows you to override the smart matching logic used by
 the C<~~> operator and the switch construct (C<given>/C<when>).  See
 L<perlsyn/switch> and L<feature>.
 
+Unusually, overloading of the smart match operator does not automatically
+take precedence over normal smart match behaviour. In particular, in the
+following code:
+
+    package Foo;
+    use overload '~~' => 'match';
+
+    my $obj =  Foo->new();
+    $obj ~~ [ 1,2,3 ];
+
+the smart match does I<not> invoke the method call like this:
+
+    $obj->match([1,2,3],0);
+
+rather, the smart match distributive rule takes precedence, so $obj is
+smart matched against each array element in turn until a match is found,
+so you may see between one and three of these calls instead:
+
+    $obj->match(1,0);
+    $obj->match(2,0);
+    $obj->match(3,0);
+
+Consult the match table in  L<perlsyn/"Smart matching in detail"> for
+details of when overloading is invoked.
+
 =item * I<Dereferencing>
 
     '${}', '@{}', '%{}', '&{}', '*{}'.
diff --git a/pod/perlsyn.pod b/pod/perlsyn.pod
index 2a83a1c4d2..cd9501211c 100644
--- a/pod/perlsyn.pod
+++ b/pod/perlsyn.pod
@@ -717,13 +717,23 @@ C<grep> does not.
 =head3 Custom matching via overloading
 
 You can change the way that an object is matched by overloading
-the C<~~> operator. This trumps the usual smart match semantics.
-See L<overload>.
+the C<~~> operator. This may alter the usual smart match semantics.
 
 It should be noted that C<~~> will refuse to work on objects that
 don't overload it (in order to avoid relying on the object's
 underlying structure).
 
+Note also that smart match's matching rules take precedence over
+overloading, so if C<$obj> has smart match overloading, then
+
+    $obj ~~ X
+
+will not automatically invoke the overload method with X as an argument;
+instead the table above is consulted as normal, and based in the type of X,
+overloading may or may not be invoked.
+
+See L<overload>.
+
 =head3 Differences from Perl 6
 
 The Perl 5 smart match and C<given>/C<when> constructs are not