Fix documentation for waitMany.

mojo/dart/packages/mojo/sdk_ext/src/natives.dart

 // Copyright 2015 The Chromium Authors. 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 internal;
 
 // Data associated with an open handle.
 class _OpenHandle {
   final StackTrace stack;
   String description;
@@ skipping 114 matching lines @@
   /// class. In particular, a successful operation returns [MojoResult.kOk].
   ///
   /// The [handleToken] is a token that identifies the Mojo handle.
   static int close(int handleToken) native "MojoHandle_Close";
 
   /// Waits on the given [handleToken] for a signal.
   ///
   /// Returns a list of two elements. The first entry is an integer, encoding
   /// if the operation was a success or not, as specified in the [MojoResult]
   /// class. In particular, a successful operation is signaled by
-  /// [MojoResult.kOk]. The second entry is itself a List of 2 elements:
+  /// [MojoResult.kOk]. The second entry is itself a list of 2 elements:
   /// an integer of satisfied signals, and an integer of satisfiable signals.
   /// Both entries are encoded as specified in [MojoHandleSignals].
   ///
+  /// A signal is satisfiable, if the signal may become true in the future.
+  ///
   /// The [deadline] specifies how long the call should wait (if no signal is
   /// triggered). If the deadline passes, the returned result-integer is
   /// [MojoResult.kDeadlineExceeded]. If the deadline is 0, then the result
   /// is only [MojoResult.kDeadlineExceeded] if no other termination condition
   /// is already satisfied (see below).
   ///
   /// The [signals] integer encodes the signals this method should wait for.
   /// The integer is encoded as specified in [MojoHandleSignals].
   ///
   /// Waits on the given handle until one of the following happens:
   /// - A signal indicated by [signals] is satisfied.
   /// - It becomes known that no signal indicated by [signals] will ever be
   ///   satisfied (for example the handle has been closed on the other side).
   /// - The [deadline] has passed.
   static List wait(int handleToken, int signals, int deadline)
       native "MojoHandle_Wait";
 
   /// Waits on many handles at the same time.
   ///
-  /// The returned value is similar to the result of [wait].
+  /// Returns a list with exactly 3 elements:
+  /// - the result integer, encoded as specified in [MojoResult]. In particular,
+  ///   [MojoResult.kOk] signals success.
+  /// - the index of the handle that caused the return. May be `null` if the
+  ///   operation didn't succeed.
+  /// - a list of signal states. May be `null` if the operation didn't succeed.
+  ///   Each signal state is represented by a list of 2 elements: an integer of
+  ///   satisfied signals, and an integer of satisfiable signals (see [wait]).
   ///
   /// Behaves as if [wait] was called on each of the [handleTokens] separately,
   /// completing when the first would complete.
   static List waitMany(List<int> handleTokens, List<int> signals, int deadline)
       native "MojoHandle_WaitMany";
 
   // Called from the embedder's unhandled exception callback.
   // Returns the number of successfully closed handles.
   static int _closeOpenHandles() {
     int count = 0;
@@ skipping 356 matching lines @@
   /// buffer.
   ///
   /// Note: there is no `unmap` call, since this is supposed to happen via
   /// finalizers.
   ///
   /// The parameter [flags] is reserved for future use and should currently be
   /// set to [MojoSharedBuffer.mapFlagNone] (equal to 0).
   static List Map(int bufferHandleToken, int offset, int numBytes, int flags)
       native "MojoSharedBuffer_Map";
 }