Extend discussion of file test operators

lib/Type/IO/FileTestable.pod

@@ -17,9 +17,10 @@ C<:e> and C<:f>.
 
 X<-M> X<-A> X<-C>
 
-    -M Does not exist in Perl 6. See C<modified>.
-    -A Does not exist in Perl 6. See C<accessed>.
-    -C Does not exist in Perl 6. See C<changed>.
+The C<-M>, C<-A> and C<-C> file test operators do not exist in Perl 6, use
+instead the L<modified|/type/IO::FileTestable#method_modified>,
+L<accessed|/type/IO::FileTestable#method_accessed> and
+L<changed|/type/IO::FileTestable#method_changed> methods instead.
 
 X<:e> X<:d> X<:f> X<:l> X<:r> X<:w> X<:x> X<:s> X<:z>
 
@@ -61,26 +62,62 @@ you can write this:
         say 'file exists';
     }
 
+=head2 File timestamp retrieval
+
 There are also 3 methods for fetching the 3 timestamps of a file (inode),
 on Operating Systems where these are available:
 
 =head2 method modified
 
-Timestamp when the file was last modified.
+Return an L<Instant> object representing the timestamp when the file was
+last modified.
+
+    say "path/to/file".IO.modified;   #  e.g. Instant:1424089165
+
+To obtain a human-readable form of the timestamp, use a L<DateTime> object:
+
+    say DateTime.new("path/to/file".IO.modified);  # e.g. 2015-02-16T12:18:50Z
 
-    "path/to/file".IO.modified()
+or more readably:
+
+    my $modification_instant = "path/to/file".IO.modified;
+    my $modification_time = DateTime.new($modification_instant);
+    say $modification_time;         # e.g. 2015-02-16T12:18:50Z
 
 =head2 method accessed
 
-Timestamp when the file was last accessed.
+Return an L<Instant> object representing the timestamp when the file was
+last accessed.
+
+    say "path/to/file".IO.accessed;   #  e.g. Instant:1424353577
+
+To obtain a human-readable form of the timestamp, use a L<DateTime> object:
 
-    "path/to/file".IO.accessed()
+    say DateTime.new("path/to/file".IO.accessed);  # e.g. 2015-02-19T13:45:42Z
+
+or more readably:
+
+    my $access_instant = "path/to/file".IO.accessed;
+    my $access_time = DateTime.new($access_instant);
+    say $access_time;         # e.g. 2015-02-19T13:45:42Z
 
 =head2 method changed
 
-Timestamp when the inode was last changed.
+Return an L<Instant> object representing the timestamp when the inode was
+last changed.
+
+    "path/to/file".IO.changed;        #  e.g. Instant:1424089165
+
+To obtain a human-readable form of the timestamp, use a L<DateTime> object:
+
+    say DateTime.new("path/to/file".IO.changed);  # e.g. 2015-02-16T12:18:50Z
+
+or more readably:
 
-    "path/to/file".IO.changed()
+    my $change_instant = "path/to/file".IO.changed;
+    my $change_time = DateTime.new($chnge_instant);
+    say $change_time;         # e.g. 2015-02-16T12:18:50Z
 
 =end pod
 
+# vim: expandtab shiftwidth=4 ft=perl6