[io grant] Document IO::Path.ACCEPTS

N.B. currently refers to undocumented `:completely` arg to .resolve.
It's not a mistake; the argument will be implemented and documented
as part of IO grant work.

Author: zoffixznet

doc/Type/IO/Path.pod6

@@ -42,6 +42,24 @@ Creates a new C<IO::Path> object from a path string (which is being parsed for
 volume, directory name and basename), or from volume, directory name and
 basename passed as named arguments.
 
+=head2 method ACCEPTS
+
+    multi method ACCEPTS(IO::Path:D: Cool:D $other --> Bool:D)
+
+Coerces the argument to C<IO::Path>, if necessary. Returns C<True> if
+L«C<.absolute>|/routine/absolute» method on both paths returns the same string.
+B<NOTE:> it's possible for two paths that superficially point to the same
+resource to NOT smartmatch as C<True>, if they were constructed differently and
+were never fully resolved:
+
+    say "foo/../bar".IO ~~ "bar".IO # False
+
+The reason is the two paths above may point to different resources when fully
+resolved (e.g. if C<foo> is a symlink). Resolve the paths before smartmatching
+to check they point to same resource:
+
+    say "foo/../bar".IO.resolve(:completely) ~~ "bar".IO.resolve(:completely) # True
+
 =head2 method basename
 
     method basename(IO::Path:D:)