Document FileSystemEntity:watch and family..

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 e930a3594d05f15cc41d1ac7099f01370eef89c0..b021ac26aba8a942632c3ec004f2fb75264af1ff 100644
--- a/sdk/lib/io/file_system_entity.dart
+++ b/sdk/lib/io/file_system_entity.dart
@@ -351,15 +351,21 @@ abstract class FileSystemEntity {
    *     files and directories. Recursive watching is not supported.
    *   * `Mac OS`: Uses `FSEvents`. The implementation supports watching both
    *     files and directories. Recursive watching is supported.
+   *     Note: events happened slightly before calling [watch], may be part of
+   *     the returned stream, on Mac OS.
    *
    * The system will start listening for events once the returned [Stream] is
    * being listened to, not when the call to [watch] is issued.
    *
-   * Note that the returned [Stream] is endless, unless:
+   * Note: that the returned [Stream] is endless, unless:
    *
    *   * The [Stream] is canceled, e.g. by calling `cancel` on the
    *      [StreamSubscription].
    *   * The [FileSystemEntity] being watches, is deleted.
+   *
+   * Use `events` to specify what events to listen for. The constants in
+   * [FileSystemEvent] can be or'ed together to mix events. Default is
+   * [FileSystemEvent.ALL].
    */
   Stream<FileSystemEvent> watch({int events: FileSystemEvent.ALL,
                                  bool recursive: false})
@@ -618,13 +624,33 @@ abstract class FileSystemEntity {
 
 
 /**
- * Base event class emitted by FileSystemWatcher.
+ * Base event class emitted by [FileSystemEntity.watch].
  */
 class FileSystemEvent {
+  /**
+   * Bitfield for [FileSystemEntity.watch], to enable [FileSystemCreateEvent]s.
+   */
   static const int CREATE = 1 << 0;
+
+  /**
+   * Bitfield for [FileSystemEntity.watch], to enable [FileSystemModifyEvent]s.
+   */
   static const int MODIFY = 1 << 1;
+
+  /**
+   * Bitfield for [FileSystemEntity.watch], to enable [FileSystemDeleteEvent]s.
+   */
   static const int DELETE = 1 << 2;
+
+  /**
+   * Bitfield for [FileSystemEntity.watch], to enable [FileSystemMoveEvent]s.
+   */
   static const int MOVE = 1 << 3;
+
+  /**
+   * Bitfield for [FileSystemEntity.watch], for enabling all of [CREATE],
+   * [MODIFY], [DELETE] and [MOVE].
+   */
   static const int ALL = CREATE | MODIFY | DELETE | MOVE;
 
   static const int _MODIFY_ATTRIBUTES = 1 << 4;