class-level docs for several dart:io classes

sdk/lib/io/file_system_entity.dart

Index: sdk/lib/io/file_system_entity.dart
diff --git a/sdk/lib/io/file_system_entity.dart b/sdk/lib/io/file_system_entity.dart
index 9a657a1ebc27ace64861815e668151c25e19d099..70ec83ee73a4db424d4dffcd3f6cbc959d495088 100644
--- a/sdk/lib/io/file_system_entity.dart
+++ b/sdk/lib/io/file_system_entity.dart
@@ -4,6 +4,14 @@
 
 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);
@@ -164,14 +172,35 @@ FileStat: type $type
 
 
 /**
- * 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.
  */
 abstract class FileSystemEntity {
   String get path;