[io grant] Document IO::Path.chdir

- Include deprecation notice for 6.d language

Author: zoffixznet

doc/Type/IO/Path.pod6

@@ -467,10 +467,23 @@ contents, and appending data to the end of the file.
 
 =item C<:$createonly> — L«C<fail>|/routine/fail» if the file already exists.
 
-=head2 routine chdir
-
-    multi method chdir(IO::Path:U: $path, :$test = 'r' --> IO::Path)
-    multi method chdir(IO::Path:D: Str() $path is copy, :$test = 'r' --> IO::Path)
+=head2 method chdir
+
+    multi method chdir(IO::Path:D: Str() $path, :$d = True, :$r, :$w, :$x)
+
+B<DEPRECATION NOTICE:> this method will be deprecated in C<6.d> language. Do
+not use it for new code. Instead, create a new path or use
+L«C<concat-with>|/routine/concat-with» method. For altering current working
+directory see L«C<&chdir>|/routine/chdir» and L«C<&*chdir>|/routine/&*chdir»
+subroutines.
+
+Contrary to the name, the C<.chdir> method does not change any directories,
+but mereley concatenates the given C<$path> to the invocant and returns the
+resultant C<IO::Path>. Optional file tests can be performed by providing
+C<:d>, C<:r>, C<:w>, or C<:x> L«C<Bool>|/type/Bool» named arguments; when
+set to C<True>, they'll perform L«C<.d>|/routine/d», L«C<.r>|/routine/r»,
+L«C<.w>|/routine/w», and L«C<.x>|/routine/x» tests respectively. By default,
+only C<:d> is set to C<True>.
 
 =head2 routine mkdir