Merge &rename, &move, &unlink documentation into /type/IO/Path.pod

Author: smls

lib/Type/IO.pod

@@ -306,42 +306,6 @@ C<False>.
     spurt "file_already_exists", "new text", :createonly;
     File 'test' already exists, and :createonly was specified
 
-=head2 sub rename
-
-    sub rename($from, $to, :$SPEC = $*SPEC, :$CWD = $*CWD, :$createonly);
-
-Moves a file, as indicated by the first positional parameter, by renaming it
-to the destination specified.  If C<:createonly> is set to C<True>, the rename fails
-if a file already exists in the destination.  Returns C<True> upon success, or
-an appropriate C<Failure> if the operation could not be completed.
-
-Please use L</move()> if a file could not be moved by renaming (usually because
-the destination is on a different physical storage device).
-
-=head2 sub move
-
-    sub move($from, $to, :$createonly);
-
-Moves a file, as indicated by the first positional parameter, by copying its
-contents to the destination specified, and then removing the file at the
-original location.  If C<:createonly> is set to C<True>, the move fails if a file
-already exists in the destination.  Returns C<True> upon success, or an
-appropriate C<Failure> if the operation could not be completed.
-
-Please use L</rename()> if a file can be moved by renaming (which is usually
-possible if the destination is on the same different physical storage device).
-Alternately, the C<move()> function is free to try the C<rename()> first,
-and if that (silently) fails, do it the hard way.
-
-B<NOTE>: This function has not yet been implemented in Rakudo.
-
-=head2 sub unlink
-
-    sub unlink(*@filenames, :$SPEC = $*SPEC, :$CWD = $*CWD);
-
-Delete all specified ordinary files, links, or symbolic links.  Returns the
-names of the files that were successfully deleted.
-
 =head2 sub run
 
     sub run(*@args ($, *@)) returns Proc::Status:D

lib/Type/IO/Path.pod

@@ -24,6 +24,11 @@ L<IO::Path::Cygwin>, L<IO::Path::QNX>.
 The rest of this document silently assumes Unix semantics in its examples,
 unless when stated otherwise.
 
+=comment TODO: Investigate if the $SPEC = $*SPEC, :$CWD = $*CWD params that
+         a bunch of these routines have in their signature in Rakudo, are
+         "official" Perl 6 API, and if so, document them here in a central
+         place so all the routine documentations can link to it without
+         having to repeat it.
 
 =head1 Methods
 
@@ -201,8 +206,7 @@ Changes the POSIX permissions of a file (or in the subroutine form, any number
 of files) to C<$mode>.
 
 The subroutine form returns the names of the files for which setting the new
-mode was successful. The method form returns True on success, and otherwise a
-C<Failure> (wrapping an C<X::IO::Chmod> exception).
+mode was successful. The method form returns True on success, and otherwise L<fails|/routine/fail> with L<X::IO::Chmod>.
 
 The mode is expected as an integer following the L<standard numeric notation|
 http://en.wikipedia.org/wiki/File_system_permissions#Numeric_notation>, and is
@@ -217,24 +221,46 @@ number (or string containing a decimal number):
 
     chmod '0444', 'myfile';            # BAD!!! (interpreted as mode 0o674)
 
-=head2 method rename
+=head2 routine rename
 
-    multi method rename(IO::Path:D: IO::Path:D $to, :$createonly);
+    method rename(IO::Path:D: $to, :$createonly --> Bool);
+    sub    rename($from, $to, :$createonly --> Bool);
 
-Like L</routine/rename()>, but with L</.absolute> as the first parameter.
+Renames a file. Both C<$from> (the file to be renamed) and C<$to> (the
+destination) can take arbitrary paths. If C<:createonly> is set to C<True>, the
+rename fails if a file already exists in the destination.  Returns C<True> upon
+success, or L<fails|/routine/fail> with L<X::IO::Rename> if the operation could
+not be completed.
 
-=head2 method move
+Please use L<move|/routine/move> if a file could not be moved by renaming (usually
+because the destination is on a different physical storage device).
 
-    method move(IO::Path:D $to, :$createonly)
+=head2 routine move
 
-Like L</routine/move()>, but with L</.absolute> as the first parameter.
+    method move(IO::Path:D: $to, :$createonly)
+    sub    move($from, $to, :$createonly);
 
-=head2 method unlink
+Moves a file. Both C<$from> (the file to be moved) and C<$to> (the destination)
+can take arbitrary paths. If C<:createonly> is set to C<True>, the move fails
+if a file already exists in the destination.  Returns C<True> upon success, or
+L<fails|/routine/fail> with L<X::IO::Move> if the operation could not be
+completed.
 
-    method unlink(IO::Path:D:);
+Please use L<rename|/routine/rename> if a file can be moved by renaming (which is
+usually possible if the destination is on the same different physical storage
+device).
 
-Like L</routine/unlink()>, but with L</.absolute> as the first parameter.
-Returns C<True> on success or an appropriate C<Failure>.
+B<NOTE>: This function has not yet been implemented in Rakudo.
+
+=head2 routine unlink
+
+    method unlink(IO::Path:D: --> Bool);
+    sub    unlink(*@filenames --> @success-filenames);
+
+Delete all specified ordinary files, links, or symbolic links.
+
+The subroutine form returns the names of the files that were successfully
+deleted. The method form returns C<True> on success, or L<fails|/routine/fail> with L<X::IO::Unlink> if the operation could not be completed.
 
 =head1 Related roles and classes