Document FileSystemEntity:watch and family..

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;
 
 class FileSystemEntityType {
   static const FILE = const FileSystemEntityType._internal(0);
   static const DIRECTORY = const FileSystemEntityType._internal(1);
   static const LINK = const FileSystemEntityType._internal(2);
@@ skipping 333 matching lines @@
    *
    * The implementation uses platform-dependent event-based APIs for receiving
    * file-system notifications, thus behavior depends on the platform.
    *
    *   * `Windows`: Uses `ReadDirectoryChangesW`. The implementation only
    *     supports watching directories. Recursive watching is supported.
    *   * `Linux`: Uses `inotify`. The implementation supports watching both
    *     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})
      => new _FileSystemWatcher(_trimTrailingPathSeparators(path),
                                events,
                                recursive).stream;
 
   Future<FileSystemEntity> _delete({bool recursive: false});
   void _deleteSync({bool recursive: false});
 
@@ skipping 238 matching lines @@
       while (path.length > 1 && path.endsWith(Platform.pathSeparator)) {
         path = path.substring(0, path.length - 1);
       }
     }
     return path;
   }
 }
 
 
 /**
- * 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;
   static const int _DELETE_SELF = 1 << 5;
 
   /**
    * The type of event. See [FileSystemEvent] for a list of events.
    */
   final int type;
 
@@ skipping 69 matching lines @@
   }
 }
 
 
 abstract class _FileSystemWatcher {
   external factory _FileSystemWatcher(String path, int events, bool recursive);
   external static bool get isSupported;
 
   Stream<FileSystemEvent> get stream;
 }