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..1a9c32c7401781a44bf6dcfd3c04cd20b833703a 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 contains all the non-overlapping matches of the
+   * pattern on the string, ordered by start index. If possible, the
+   * matches are computed on demand. If a user only requests the first
+   * match, this function should not compute all possible matches.

[Lasse Reichstein Nielsen, 2015/08/11 10:15:39]

Drop the "if possible" - just require it. It's an oversight that it doesn't say
so, and I don't think there are any implementations that does it wrong (there
aren't that many pattern implementations at all).

The returned iterable lazily computes ...

[floitsch, 2015/08/11 11:25:25]

Unfortunately the String.allMatches does it wrong (both on dart2js and the VM).
I will try to fix them.
Done.

    *
    * The matches are found by repeatedly finding the first match
    * of the pattern on the string, starting from the end of the previous