class-level docs for several dart:io classes

sdk/lib/io/file_system_entity.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 type of an entity on the file system, such as a file, directory, or link.
+ *
+ * These constants are used by the [FileSystemEntity] class
+ * to indicate the object's type.
+ *
+ */
+
 class FileSystemEntityType {
   static const FILE = const FileSystemEntityType._internal(0);
   static const DIRECTORY = const FileSystemEntityType._internal(1);
   static const LINK = const FileSystemEntityType._internal(2);
   static const NOT_FOUND = const FileSystemEntityType._internal(3);
   static const _typeList = const [FileSystemEntityType.FILE,
                                   FileSystemEntityType.DIRECTORY,
                                   FileSystemEntityType.LINK,
                                   FileSystemEntityType.NOT_FOUND];
   final int _type;
@@ skipping 140 matching lines @@
     result
         ..add(codes[(permissions >> 6) & 0x7])
         ..add(codes[(permissions >> 3) & 0x7])
         ..add(codes[permissions & 0x7]);
     return result.join();
   }
 }
 
 
 /**
- * A [FileSystemEntity] is a common super class for [File] and
- * [Directory] objects.
+ * The common super class for [File], [Directory], and [Link] objects.
  *
  * [FileSystemEntity] objects are returned from directory listing
- * operations. To determine if a FileSystemEntity is a [File] or a
- * [Directory], perform a type check:
+ * operations. To determine if a FileSystemEntity is a [File], a
+ * [Directory], or a [Link] perform a type check:
  *
  *     if (entity is File) (entity as File).readAsStringSync();
+ *
+ * You can also use the [type] or [typeSync] methods to determine
+ * the type of a file system object.
+ *
+ * Most methods in this class occur in synchronous and asynchronous pairs,
+ * for example, [exists] and [existsSync].
+ * Unless you have a specific reason for using the synchronous version
+ * of a method, prefer the asynchronous version to avoid blocking your program.
+ *
+ * Here's the exists method in action:
+ *
+ *     entity.exists().then((isThere) {
+ *       isThere ? print('exists') : print('non-existent');
+ *     });
+ *
+ *
+ * ## 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 [File] class,
+ * both subclasses of FileSystemEntity.
+ *
+ * * [I/O for Command-Line Apps](https://www.dartlang.org/docs/dart-up-and-running/contents/ch03.html#ch03-dartio---file-and-socket-io-for-command-line-apps)
+ * a section from _A Tour of the Dart Libraries_
+ * covers files and directories.
+ *
+ * * [Write Command-Line Apps](https://www.dartlang.org/docs/tutorials/cmdline/),
+ * a tutorial about writing command-line apps, includes information
+ * about files and directories.
+
  */
 abstract class FileSystemEntity {
   String get path;
 
   /**
    * Checks whether the file system entity with this path exists. Returns
    * a [:Future<bool>:] that completes with the result.
    *
    * Since FileSystemEntity is abstract, every FileSystemEntity object
    * is actually an instance of one of the subclasses [File],
@@ skipping 583 matching lines @@
     return buffer.toString();
   }
 }
 
 
 class _FileSystemWatcher {
   external static Stream<FileSystemEvent> watch(
       String path, int events, bool recursive);
   external static bool get isSupported;
 }