From 3f1eec012ac9ab120b5e7edd606f1751698941cb Mon Sep 17 00:00:00 2001
From: Chad Granum <exodist7@gmail.com>
Date: Sat, 13 Aug 2016 14:25:29 -0700
Subject: [PATCH] Add documentation for is_deeply limitations

Fixes #595
---
 Changes               |  2 ++
 lib/Test/More.pm      | 14 ++++++++++++++
 xt/author/pod-spell.t |  1 +
 3 files changed, 17 insertions(+)

diff --git a/Changes b/Changes
index 5be526558..1b152025c 100644
--- a/Changes
+++ b/Changes
@@ -1,5 +1,7 @@
 {{$NEXT}}
 
+    - Document limitations in is_deeply (#595)
+
 1.302051  2016-08-11 20:26:22-07:00 America/Los_Angeles (TRIAL RELEASE)
 
     - Fix setting hub when getting context
diff --git a/lib/Test/More.pm b/lib/Test/More.pm
index 205199309..78c21ec52 100644
--- a/lib/Test/More.pm
+++ b/lib/Test/More.pm
@@ -1064,6 +1064,20 @@ improve in the future.
 L<Test::Differences> and L<Test::Deep> provide more in-depth functionality
 along these lines.
 
+B<NOTE> is_deeply() has limitations when it comes to comparing strings and
+refs:
+
+    my $path = path('.');
+    my $hash = {};
+    is_deeply( $path, "$path" ); # ok
+    is_deeply( $hash, "$hash" ); # fail
+
+This happens because is_deeply will unoverload all arguments unconditionally.
+It is probably best not to use is_deeply with overloading. For legacy reasons
+this is not likely to ever be fixed. If you would like a much better tool for
+this you should see L<Test2::Suite> Specifically L<Test2::Tools::Compare> has
+an C<is()> function that works like C<is_deeply> with many improvements.
+
 =cut
 
 our( @Data_Stack, %Refs_Seen );
diff --git a/xt/author/pod-spell.t b/xt/author/pod-spell.t
index 6fe474fa3..3fd493ab0 100644
--- a/xt/author/pod-spell.t
+++ b/xt/author/pod-spell.t
@@ -87,6 +87,7 @@ subevents
 testability
 TIEHANDLE
 tie-ing
+unoverload
 VMS
 vmsperl
 YESNO