[dart:io] Adds functions to set file access and modification time

sdk/lib/io/file.dart

 // Copyright (c) 2013, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 part of dart.io;
 
 /**
  * The modes in which a File can be opened.
  */
 class FileMode {
@@ skipping 292 matching lines @@
   /**
    * Returns a [File] instance whose path is the absolute path to [this].
    *
    * The absolute path is computed by prefixing
    * a relative path with the current working directory, and returning
    * an absolute path unchanged.
    */
   File get absolute;
 
   /**
-   * Get the last-modified time of the file. Returns a
+   * Gets the last-accessed time of the file. Returns a
+   * [:Future<DateTime>:] that completes with a [DateTime] object for the

[Lasse Reichstein Nielsen, 2017/02/09 15:28:03]

Comment is badly formatted (because it predates the style guide).
Something like:

/**
 * Get the last-accessed time of the file.
 *
 * Returns the date and time where the file was last accessed, if the
information
 * is available.
 *  
 * Throws a [FileSystemException] if the operation fails.
 */

(I don't mention the future, it's obvious from the return type that the function
is asynchronous).
I assume this fails in the same way as the sync version, only through the
future.

[floitsch, 2017/02/09 16:19:34]

Also, please use back-ticks for code: `Future<DateTime>`.

[zra, 2017/02/09 17:21:38]

Done.

[zra, 2017/02/09 17:21:39]

Acknowledged.

+   * access date.
+   */
+  Future<DateTime> lastAccessed();

[Lasse Reichstein Nielsen, 2017/02/09 15:28:03]

Feels like it should be a getter ... but there is an asynchronous setter
function corresponding to it, so it's probably best to be a function.

The sync version really should have been a getter/setter, but that's
inconsistent with lastModified(). Ack, failures of the past coming back to bite
us now :(

[floitsch, 2017/02/09 16:19:34]

It should still be a getter: `lastAccessed` is a field/getter name.
If it's preferable to keep the function, then it should change the name:
getLastAccessed, computeLastAccessed, ...

Edit: for consistency keep the function. I just saw that many others here are
also functions.
The IO library is unfortunately really bad in this respect. Not much we can do
now.

[zra, 2017/02/09 17:21:39]

Acknowledged.

[zra, 2017/02/09 17:21:39]

Acknowledged.

+
+  /**
+   * Gets the last-accessed time of the file. Throws an exception
+   * if the file does not exist.
+   *
+   * Throws a [FileSystemException] if the operation fails.

[Lasse Reichstein Nielsen, 2017/02/09 15:28:03]

/**
 * Get the last-accessed time of the file.
 *
 * Blocks until the information is available.
 * Returns the date and time where the file was last accessed, 
 * if the information is available.
 *
 * Throws a [FileSystemException] if the operation fails.
 */

[floitsch, 2017/02/09 16:19:35]

Agree with Lasse:
As a general guideline: Start with a first short sentence that would be the
header in a dartdoc.

Start the sentence that talks about the return value with 'Returns'.

In addition to Lasse's change I would add a new line between the 'Throws' and
'Return' sentence, so that they are separate paragraphs in dartdoc.

Personally I find the return value more important and would put the 'Return'
sentence first.

[zra, 2017/02/09 17:21:39]

Done.

[zra, 2017/02/09 17:21:39]

Acknowledged.

+   */
+  DateTime lastAccessedSync();
+
+  /**
+   * Modifies the time the file was last accessed.
+   *
+   * Returns a [:Future<File>:] that completes with this

[floitsch, 2017/02/09 16:19:34]

Please use `backticks` for code. The [:old_style:] is being phased out and
almost never used anymore.

(backticks have the advantage of being compatible with markdown).

[zra, 2017/02/09 17:21:39]

Replaced here and elsewhere.

+   * [File] when the attributes have been set. If the access time

[Lasse Reichstein Nielsen, 2017/02/09 15:28:03]

attributes have -> time has
(there is only one attribute here, the time)

[zra, 2017/02/09 17:21:39]

Done.

+   * cannot be set, the future completes with an exception.
+   */
+  Future<File> setLastAccessed(DateTime time);

[Lasse Reichstein Nielsen, 2017/02/09 15:28:03]

Just return Future, and complete with null.

[zra, 2017/02/09 17:21:39]

Done.

+
+  /**
+   * Synchronously modifies the time the file was last accessed.
+   *
+   * If the attributes cannot be set, throws a [FileSystemException].

[Lasse Reichstein Nielsen, 2017/02/09 15:28:03]

attributes -> attribute (or just "time").

I'd prefer the sentence as:
* Throws a [FilsSystemException] if the time cannot be set.
It's always good to start paragraphs with "returns" or "throws" so it's easy to
find when you scan the docs.

[zra, 2017/02/09 17:21:39]

Done.

+   */
+  File setLastAccessedSync(DateTime time);

[Lasse Reichstein Nielsen, 2017/02/09 15:28:03]

Return void.

[zra, 2017/02/09 17:21:38]

Done.

+
+  /**
+   * Gets the last-modified time of the file. Returns a
    * [:Future<DateTime>:] that completes with a [DateTime] object for the
    * modification date.
    */
   Future<DateTime> lastModified();
 
   /**
-   * Get the last-modified time of the file. Throws an exception
+   * Gets the last-modified time of the file. Throws an exception
    * if the file does not exist.
    *
    * Throws a [FileSystemException] if the operation fails.
    */
   DateTime lastModifiedSync();
 
   /**
+   * Modifies the time the file was last modified.
+   *
+   * Returns a [:Future<File>:] that completes with this
+   * [File] when the attributes have been set. If the modification
+   * time cannot be set, the future completes with an exception.
+   */
+  Future<File> setLastModified(DateTime time);

[Lasse Reichstein Nielsen, 2017/02/09 15:28:03]

Just return a `Future` that is completed with `null`.

[zra, 2017/02/09 17:21:39]

Done.

+
+  /**
+   * Synchronously modifies the time the file was last modified.
+   *
+   * If the attributes cannot be set, throws a [FileSystemException].
+   */
+  File setLastModifiedSync(DateTime time);

[Lasse Reichstein Nielsen, 2017/02/09 15:28:03]

Should just return void.

[zra, 2017/02/09 17:21:39]

Done.

+
+  /**
    * Open the file for random access operations. Returns a
    * [:Future<RandomAccessFile>:] that completes with the opened
    * random access file. [RandomAccessFile]s must be closed using the
    * [RandomAccessFile.close] method.
    *
    * Files can be opened in three modes:
    *
    * [FileMode.READ]: open the file for reading.
    *
    * [FileMode.WRITE]: open the file for both reading and writing and
@@ skipping 552 matching lines @@
       sb.write(": $osError");
       if (path != null) {
         sb.write(", path = '$path'");
       }
     } else if (path != null) {
       sb.write(": $path");
     }
     return sb.toString();
   }
 }