Clarify FSEvent API limitations.

TEST=doc only
Bug: #14373
Change-Id: I973a794f086316ef99679a55c80327095e6456a7
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/268610
Reviewed-by: Alexander Aprelev <aam@google.com>
Commit-Queue: Brian Quinlan <bquinlan@google.com>

sdk/lib/io/file_system_entity.dart

@@ -434,8 +434,18 @@ abstract class FileSystemEntity {
   ///     files and directories. Recursive watching is not supported.
   ///     Note: When watching files directly, delete events might not happen
   ///     as expected.
-  ///   * `OS X`: Uses `FSEvents`. The implementation supports watching both
-  ///     files and directories. Recursive watching is supported.
+  ///   * `OS X`: Uses the
+  ///     [File System Events API](https://developer.apple.com/library/archive/documentation/Darwin/Conceptual/FSEvents_ProgGuide/TechnologyOverview/TechnologyOverview.html).
+  ///     The implementation supports watching both files and directories.
+  ///     Recursive watching is supported.
+  ///     This API has several limitations:
+  ///
+  ///     * Changes that occurred shortly *before* the [watch] method was
+  ///       called may still appear in the [Stream].
+  ///     * Changes that occur in a short period of time may arrive
+  ///       out-of-order.
+  ///     * Multiple changes made in a single directory may be coalesced into
+  ///       a single `FileSystemEvent`.
   ///
   /// The system will start listening for events once the returned [Stream] is
   /// being listened to, not when the call to [watch] is issued.