[io grant] Improve chmod docs

- Split sub and method forms, as they're very different.
- Remove $*CWD example; bad form without `temp`ing it first.
- Add examples for chmoding dirs too
- Add examples with an octal in a string

Author: zoffixznet

doc/Type/IO.pod6

@@ -81,6 +81,17 @@ you do not need to change process's current directory:
     temp $*CWD;
     &*chdir('/tmp');
 
+=head2 sub chmod
+
+    sub chmod(Int() $mode, *@filenames --> List)
+
+Coerces all C<@filenames> to L«C<IO::Path>|/type/IO::Path» and calls
+L«C<IO::Path.chmod>|/type/IO::Path#method_chmod» with C<$mode> on them.
+Returns a L«C<List>|/type/List» containing a subset of C<@filenames> for which
+C<chmod> was successfully executed.
+
+    chmod 0o755, <myfile1  myfile2>; # make two files executable by the owner
+
 =head2 sub indir
 
 Defined as:

doc/Type/IO/Path.pod6

@@ -528,32 +528,29 @@ contents you will have to do something more complex.
 
 See also L<rmtree in File::Directory::Tree|https://github.com/labster/p6-file-directory-tree>.
 
-=head2 routine chmod
+=head2 method chmod
 
-    sub    chmod($mode, *@filenames --> List)
-    method chmod(IO::Path:D: $mode --> Bool)
+    method chmod(IO::Path:D: Int() $mode --> Bool)
 
-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
+Changes the POSIX permissions of a file or directory to C<$mode>.
+Returns C<True> on success; on failure,
 L<fails|/routine/fail> with L<X::IO::Chmod>.
 
 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:
 
 =for code :skip-test
-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
+'myfile'.IO.chmod(0o444);          # make a file read-only
+'somedir'.IO.chmod(0o777);         # set 0777 permissions on a directory
 
 Make sure you I<don't> accidentally pass the intended octal digits as a decimal
 number (or string containing a decimal number):
 
 =for code :skip-test
-chmod '0444', 'myfile';            # BAD!!! (interpreted as mode 0o674)
+chmod  '0444', 'myfile';           # BAD!!! (interpreted as mode 0o674)
+chmod '0o444', 'myfile';           # OK (an octal in a string)
+chmod  0o444,  'myfile';           # Also OK (an octal literal)
 
 =head2 routine rename