JDK 9 RFR(s): 8150488: add note to Scanner.findAll() regarding possible infinite streams

[Stuart Marks]

Hi all,

Please review these non-normative textual additions to the Scanner.findAll() 
method docs. These methods were added earlier in JDK 9; there's a small pitfall 
if the regex can match zero characters.

Thanks,

s'marks


# HG changeset patch
# User smarks
# Date 1490749958 25200
#      Tue Mar 28 18:12:38 2017 -0700
# Node ID 6b43c4698752779793d58813f46d3687c17dde75
# Parent  fb54b256d751ae3191e9cef42ff9f5630931f047
8150488: add note to Scanner.findAll() regarding possible infinite streams
Reviewed-by: XXX

diff -r fb54b256d751 -r 6b43c4698752 
src/java.base/share/classes/java/util/Scanner.java
--- a/src/java.base/share/classes/java/util/Scanner.java	Mon Mar 27 15:12:01 
2017 -0700
+++ b/src/java.base/share/classes/java/util/Scanner.java	Tue Mar 28 18:12:38 
2017 -0700
@@ -2808,6 +2808,10 @@
       * }
       * }</pre>
       *
+     * <p>The pattern must always match at least one character. If the pattern
+     * can match zero characters, the result will be an infinite stream
+     * of empty matches.
+     *
       * @param pattern the pattern to be matched
       * @return a sequential stream of match results
       * @throws NullPointerException if pattern is null
@@ -2829,6 +2833,11 @@
       *     scanner.findAll(Pattern.compile(patString))
       * }</pre>
       *
+     * @apiNote
+     * The pattern must always match at least one character. If the pattern
+     * can match zero characters, the result will be an infinite stream
+     * of empty matches.
+     *
       * @param patString the pattern string
       * @return a sequential stream of match results
       * @throws NullPointerException if patString is null