Update watch docs.

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
@@ skipping 400 matching lines @@
    * The returned value is an endless broadcast [Stream], that only stops when
    * one of the following happends:
    *
    *   * 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].
+   *
+   * If the system is unable to pair a move-event, the event may be rewritten

[Søren Gjesse, 2014/09/23 11:21:41]

This is a bit out of the blue. There is no mentioning of paring move events
above, so some more documentation is needed here.

[Anders Johnsen, 2014/09/23 11:30:07]

Simplified a bit - no longer any mention to how we do things.

+   * to a delete and create event.
    */
   Stream<FileSystemEvent> watch({int events: FileSystemEvent.ALL,
                                  bool recursive: false})
      => _FileSystemWatcher.watch(_trimTrailingPathSeparators(path),
                                  events,
                                  recursive);
 
   Future<FileSystemEntity> _delete({bool recursive: false});
   void _deleteSync({bool recursive: false});
 
@@ skipping 375 matching lines @@
     return buffer.toString();
   }
 }
 
 
 class _FileSystemWatcher {
   external static Stream<FileSystemEvent> watch(
       String path, int events, bool recursive);
   external static bool get isSupported;
 }