class-level docs for several dart:io classes

sdk/lib/io/directory.dart

 // Copyright (c) 2012, 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;
 
 /**

[Søren Gjesse, 2014/02/12 13:16:35]

We should have a section on the fact that Directory is both used as an instance
to access the file system and has a number of static methods 'systemTemp' and
'current' (which are not related to a specific directory.

[mem, 2014/02/12 19:17:07]

Done.

  * A reference to a directory (or _folder_) on the file system.
+ *
+ * A [Directory] has a [path] (the pathname to the directory) and a [parent]

[Søren Gjesse, 2014/02/12 13:16:35]

We should merge this with the first line, and be precise about the fact that a
Directory instance is just an object holding a path on which operations can be
performed.

We should also mention that the path can be either relative or absolute.

The [parent] property is not directly part of the Directory.

[mem, 2014/02/12 19:17:07]

The convention is to have a single one-liner that starts with a noun to start.
Then move to a full directory.

Made adjustments tho to accommodate your comments.

Otherwise, done.

On 2014/02/12 13:16:35, Søren Gjesse wrote:

+ * (the directory that contains this directory).
+ * Create a new Directory object with a pathname to access the directory on
+ * the file system from your program.
+ *
+ *     var myDir = new Directory('myDir');
+ *
+ * Most methods in this class occur in synchronous and asynchronous pairs,
+ * for example, [create] and [createSync].
+ * Unless you have a specific reason for using the synchronous version
+ * of a method, prefer the asynchronous version to avoid blocking your program.
+ *
+ * ## Create a directory
+ *
+ * The following code sample creates a directory using the [create] method.
+ * By setting the `recursive` parameter to true, you can create the
+ * named directory and all its necessary parent directories,
+ * if they do not already exist.
+ *
+ *     import 'dart:io';
+ *
+ *     void main() {
+ *       // Creates dir/ and dir/subdir/.
+ *       new Directory('dir/subdir').create(recursive: true)
+ *         // The created directory is returned as a Future.
+ *         .then((Directory directory) {
+ *           print(directory.path);
+ *       });
+ *     }
+ * 
+ * ## List a directory
+ *
+ * Use the [list] or [listSync] methods to get the files and directories
+ * contained by a directory.
+ * Set `recursive` to true to recursively list all subdirectories.
+ * Set `followLinks` to true to follow symbolic links.
+ * The list method returns a Stream that serves FileSystemEntity

[Søren Gjesse, 2014/02/12 13:16:35]

serves -> provides

(serves is OK, but I think provides is a bit better)

[mem, 2014/02/12 19:17:07]

Done.

+ * objects.
+ *
+ *     import 'dart:io';
+ *
+ *     void main() {
+ *       // Get the system temp directory.
+ *       var systemTempDir = Directory.systemTemp;
+ *
+ *       // List directory contents, recursing into sub-directories,
+ *       // but not following symbolic links.
+ *       systemTempDir.list(recursive: true, followLinks: false)
+ *         .listen((FileSystemEntity entity) {
+ *           print(entity.path);
+ *         });
+ *     }
+ *
+ * ## The use of Futures
+ *
+ * To avoid unintentional blocking of the program,

[Søren Gjesse, 2014/02/12 13:16:35]

Maybe we should rephrase this somehow, e.g.

Whenever an I/O operation is performed the running program could block for some
period of time waiting for the operation to complete. To avoid this all
operations involving I/O has a asynchronous variant which returns a future. This
future completes when the I/O operation has finished. While the I/O operation is
in progress the Dart program is not blocked, but can perform other operations.

... maybe that is a bit long?

[mem, 2014/02/12 19:17:07]

Done.

+ * several methods use a [Future] to return a value. For example,
+ * the [exists] method, which determines whether the directory exists,
+ * returns a boolean value using a Future.
+ * Use `then` to register a callback function, which is called when
+ * the value is ready.
+ *
+ *     import 'dart:io';
+ *
+ *     main() {
+ *       final myDir = new Directory('dir');
+ *       myDir.exists().then((isThere) {
+ *         isThere ? print('exists') : print('non-existent');
+ *       });
+ *     }
+ *
+ *
+ * In addition to exists, the [stat], [rename], and
+ * other methods, return Futures.
+ *
+ * ## Other resources
+ *
+ * [Dart by Example](https://www.dartlang.org/dart-by-example/#files-directories-and-symlinks)
+ * provides additional task-oriented code samples that show how to use 
+ * various API from the Directory class and the related [File] class.
+ *
  */
 abstract class Directory implements FileSystemEntity {
   /**
    * Gets the path of this directory.
    */
   final String path;
 
   /**
    * Creates a directory object. The path is either an absolute path,
    * or it is a relative path which is interpreted relative to the directory
@@ skipping 168 matching lines @@
    * directories, files, and links.
    */
   List<FileSystemEntity> listSync({bool recursive: false,
                                    bool followLinks: true});
 
   /**
    * Returns a human readable string for this Directory instance.
    */
   String toString();
 }