Document &chmod

Author: smls

lib/Type/IO/Path.pod

@@ -152,13 +152,30 @@ An example that lists all files and directories recursively:
         }
     }
 
-=head2 method chmod
+=head2 routine chmod
 
-    method chmod(IO::Path:D: Int:D $mode)
+    sub    chmod($mode, *@filenames --> @success-filenames)
+    method chmod(IO::Path:D: $mode --> Bool)
 
-Changes the POSIX permissions of a file to C<$mode>.
+Changes the POSIX permissions of a file (or in the subroutine form, any number
+of files) to C<$mode>.
 
-    "myfile".IO.chmod(0o755);
+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).
+
+The mode is expected as an integer following the L<standard numeric notation|
+https://en.wikipedia.org/wiki/File_system_permissions#Numeric_notation>, and is
+best written as an octal number:
+
+    chmod 0o755, "myfile1", "myfile2"; # make two files executable by the owner
+    "myfile".IO.chmod(0o444);          # make a file read-only
+    $*CWD.chmod(0o544);                # make the working directory read-only
+
+Make sure you I<don't> accidentally pass the intended octal digits as a decimal
+number (or string containing a decimal number):
+
+    chmod '0444', 'myfile';            # BAD!!! (interpreted as mode 0o674)
 
 =head2 method rename