Improve documentation for Pattern.allMatches.

sdk/lib/core/pattern.dart

Index: sdk/lib/core/pattern.dart
diff --git a/sdk/lib/core/pattern.dart b/sdk/lib/core/pattern.dart
index cf898afff379470ed7a4baf08cc1e548e30831ee..f47ba156df73e3b40806924ff25986f19e194b89 100644
--- a/sdk/lib/core/pattern.dart
+++ b/sdk/lib/core/pattern.dart
@@ -17,8 +17,10 @@ abstract class Pattern {
    *
    * If [start] is provided, matching will start at that index.
    *
-   * The iterable will contain all the non-overlapping matches of the
-   * pattern on the string, ordered by start index.
+   * The returned iterable lazily computes all the non-overlapping matches
+   * of the pattern on the string, ordered by start index.
+   * If a user only requests the first
+   * match, this function should not compute all possible matches.
    *
    * The matches are found by repeatedly finding the first match
    * of the pattern on the string, starting from the end of the previous