RFR 8014383: StringJoiner example in class description not in sync with streams API

[Paul Sandoz]

Hi,

Please review this JavaDoc fix to j.u.StringJoiner to update and move the examples to an api note.

--

This has already been fixed in the lambda repo:

http://hg.openjdk.java.net/lambda/lambda/jdk/rev/3a44a6038054

Paul.

# HG changeset patch
# User psandoz
# Date 1369996938 -7200
# Node ID 2154bb2da653d83abddc23960a45e29980248ada
# Parent  486e5091ed999ebf65a92a6d862bbcf47bf9bc78
8014383: StringJoiner example in class description not in sync with streams API
Reviewed-by:

diff -r 486e5091ed99 -r 2154bb2da653 src/share/classes/java/util/StringJoiner.java
--- a/src/share/classes/java/util/StringJoiner.java	Fri May 31 10:53:19 2013 +0200
+++ b/src/share/classes/java/util/StringJoiner.java	Fri May 31 12:42:18 2013 +0200
@@ -29,14 +29,6 @@
  * by a delimiter and optionally starting with a supplied prefix
  * and ending with a supplied suffix.
  * <p>
- * For example, the String {@code "[George:Sally:Fred]"} may
- * be constructed as follows:
- * <pre> {@code
- *     StringJoiner sj = new StringJoiner(":", "[", "]");
- *     sj.add("George").add("Sally").add("Fred");
- *     String desiredString = sj.toString();
- * }</pre>
- * <p>
  * Prior to adding something to the {@code StringJoiner}, its
  * {@code sj.toString()} method will, by default, return {@code prefix + suffix}.
  * However, if the {@code setEmptyValue} method is called, the {@code emptyValue}
@@ -45,17 +37,28 @@
  * <code>"{}"</code>, where the {@code prefix} is <code>"{"</code>, the
  * {@code suffix} is <code>"}"</code> and nothing has been added to the
  * {@code StringJoiner}.
+ *
+ * @apiNote
+ * <p>The String {@code "[George:Sally:Fred]"} may be constructed as follows:
+ *
+ * <pre> {@code
+ * StringJoiner sj = new StringJoiner(":", "[", "]");
+ * sj.add("George").add("Sally").add("Fred");
+ * String desiredString = sj.toString();
+ * }</pre>
  * <p>
  * A {@code StringJoiner} may be employed to create formatted output from a
- * collection using lambda expressions as shown in the following example.
+ * {@link java.util.stream.Stream} using
+ * {@link java.util.stream.Collectors#toStringJoiner}. For example:
  *
  * <pre> {@code
- *     List<Person> people = ...
- *     String commaSeparatedNames =
- *         people.map(p -> p.getName()).into(new StringJoiner(", ")).toString();
+ * List<Integer> numbers = Arrays.asList(1, 2, 3, 4);
+ * String commaSeparatedNumbers = numbers.stream()
+ *     .map(i -> i.toString())
+ *     .collect(Collectors.toStringJoiner(", ")).toString();
  * }</pre>
  *
- * @author Jim Gish
+ * @see java.util.stream.Collectors#toStringJoiner
  * @since  1.8
 */
 public final class StringJoiner {