--- a/src/share/classes/java/util/stream/IntStream.java	Fri Feb 22 17:51:40 2013 -0500
+++ b/src/share/classes/java/util/stream/IntStream.java	Fri Feb 22 18:25:12 2013 -0500
@@ -64,6 +64,7 @@
      * Transform this stream into one consisting of the elements that match the given {@code IntPredicate}.  This is
      * an <a href="package-summary.html#StreamOps">intermediate operation</a>.
      * @param predicate The test criteria to apply to each element to determine if it should be included in the output
+     * @return the new stream
      */
     IntStream filter(IntPredicate predicate);
 
@@ -71,6 +72,7 @@
      * Transform this stream into one consisting of the result of applying the given function to the
      * elements of this stream.  This is an <a href="package-summary.html#StreamOps">intermediate operation</a>.
      * @param mapper The function to be applied to each element
+     * @return the new stream
      */
     IntStream map(IntUnaryOperator mapper);
 
@@ -78,6 +80,7 @@
      * Transform this stream into one consisting of the result of applying the given function to the
      * elements of this stream.  This is an <a href="package-summary.html#StreamOps">intermediate operation</a>.
      * @param mapper The function to be applied to each element
+     * @return the new stream
      */
     <U> Stream<U> map(IntFunction<U> mapper);
 
@@ -89,6 +92,7 @@
      * This implementation is generally less efficient than the other form of
      * {@link #flatMap(FlatMapper.OfIntToInt)}, and is provided for convenience.
      * @param mapper The function to be applied to each element, resulting in an {@code IntStream} of new values
+     * @return the new stream
      */
     default IntStream flatMap(IntFunction<? extends IntStream> mapper) {
         return flatMap((int i, IntConsumer sink) -> mapper.apply(i).sequential().forEach(sink));
@@ -104,8 +108,8 @@
      * stream of prime factors of those numbers:
      * <pre>
      *     stringStream.flatMap((elt, destination) -> {
-     *                              for (i=2; i < elt; i++)
-     *                                  if (elt % i == 0 && isPrime(i))
+     *                              for (i=2; i &lt; elt; i++)
+     *                                  if (elt % i == 0 &amp;&amp; isPrime(i))
      *                                  destination.accept(i);
      *                          })
      *                 ...
@@ -115,6 +119,7 @@
      * but is often considerably more efficient because it eliminates the overhead of stream construction and
      * traversal.
      * @param mapper The {@code FlatMapper.OfIntToInt} that transforms each element into zero or more resulting values
+     * @return the new stream
      */
     IntStream flatMap(FlatMapper.OfIntToInt mapper);
 

--- a/src/share/classes/java/util/stream/Stream.java	Fri Feb 22 17:51:40 2013 -0500
+++ b/src/share/classes/java/util/stream/Stream.java	Fri Feb 22 18:25:12 2013 -0500
@@ -73,6 +73,7 @@
      * Transform this stream into one consisting of the elements that match the given {@code Predicate}.  This is
      * an <a href="package-summary.html#StreamOps">intermediate operation</a>.
      * @param predicate The test criteria to apply to each element to determine if it should be included in the output
+     * @return the new stream
      */
     Stream<T> filter(Predicate<? super T> predicate);
 
@@ -80,6 +81,7 @@
      * Transform this stream into one consisting of the result of applying the given {@code Function} to the
      * elements of this stream.  This is an <a href="package-summary.html#StreamOps">intermediate operation</a>.
      * @param mapper The function to be applied to each element
+     * @return the new stream
      */
     <R> Stream<R> map(Function<? super T, ? extends R> mapper);
 
@@ -87,6 +89,7 @@
      * Transform this stream into an {@code IntStream} consisting of the result of applying the given function
      * to the elements of this stream.  This is an <a href="package-summary.html#StreamOps">intermediate operation</a>.
      * @param mapper The function to be applied to each element
+     * @return the new stream
      */
     IntStream map(ToIntFunction<? super T> mapper);
 
@@ -94,6 +97,7 @@
      * Transform this stream into a {@code LongStream} consisting of the result of applying the given function
      * to the elements of this stream.  This is an <a href="package-summary.html#StreamOps">intermediate operation</a>.
      * @param mapper The function to be applied to each element
+     * @return the new stream
      */
     LongStream map(ToLongFunction<? super T> mapper);
 
@@ -101,6 +105,7 @@
      * Transform this stream into a {@code DoubleStream} consisting of the result of applying the given function
      * to the elements of this stream.  This is an <a href="package-summary.html#StreamOps">intermediate operation</a>.
      * @param mapper The function to be applied to each element
+     * @return the new stream
      */
     DoubleStream map(ToDoubleFunction<? super T> mapper);
 
@@ -118,6 +123,7 @@
      * This implementation is generally less efficient than the other form of {@link #flatMap(FlatMapper)}, and is
      * provided for convenience.
      * @param mapper The function to be applied to each element, resulting in a {@code Stream} of new values
+     * @return the new stream
      */
     default <R> Stream<R> flatMap(Function<T, Stream<? extends R>> mapper) {
         // We can do better than this, by polling cancellationRequested when stream is infinite
@@ -134,7 +140,7 @@
      * stream of the characters in those strings, you would do:
      * <pre>
      *     stringStream.flatMap((elt, destination) -> {
-     *                              for (i=0; i < elt.length(); i++)
+     *                              for (i=0; i &lt; elt.length(); i++)
      *                                  destination.accept(charAt(i));
      *                          })
      *                 ...
@@ -144,6 +150,7 @@
      * but is often considerably more efficient because it eliminates the overhead of stream construction and
      * traversal.
      * @param mapper The {@code FlatMapper} that transforms each element into zero or more resulting values
+     * @return the new stream
      */
     <R> Stream<R> flatMap(FlatMapper<? super T, R> mapper);
 
@@ -152,8 +159,9 @@
      * values, according to the transformation encoded in the provided {@code FlatMapper.OfInt}.  This is
      * an <a href="package-summary.html#StreamOps">intermediate operation</a>.
      *
-     * @see {@link #flatMap(FlatMapper)}
+     * @see #flatMap(FlatMapper)
      * @param mapper The {@code FlatMapper} that transforms each element into zero or more resulting values
+     * @return the new stream
      */
     IntStream flatMap(FlatMapper.ToInt<? super T> mapper);
 
@@ -162,8 +170,9 @@
      * values, according to the transformation encoded in the provided {@code FlatMapper.OfLong}.  This is
      * an <a href="package-summary.html#StreamOps">intermediate operation</a>.
      *
-     * @see {@link #flatMap(FlatMapper)}
+     * @see #flatMap(FlatMapper)
      * @param mapper The {@code FlatMapper} that transforms each element into zero or more resulting values
+     * @return the new stream
      */
     LongStream flatMap(FlatMapper.ToLong<? super T> mapper);
 
@@ -172,8 +181,9 @@
      * values, according to the transformation encoded in the provided {@code FlatMapper.OfDouble}.  This is
      * an <a href="package-summary.html#StreamOps">intermediate operation</a>.
      *
-     * @see {@link #flatMap(FlatMapper)}
+     * @see #flatMap(FlatMapper)
      * @param mapper The {@code FlatMapper} that transforms each element into zero or more resulting values
+     * @return the new stream
      */
     DoubleStream flatMap(FlatMapper.ToDouble<? super T> mapper);
 
@@ -181,6 +191,7 @@
      * Transform this stream into one consisting of the distinct elements (according to
      * {@link Object#equals(Object)}) of this stream.  This is
      * a <a href="package-summary.html#StreamOps">stateful intermediate operation</a>.
+     * @return the new stream
      */
     Stream<T> distinct();
 
@@ -189,6 +200,7 @@
      * order.  If the elements of this stream are not {@code Comparable}, a {@code java.lang.ClassCastException}
      * may be thrown when the stream pipeline is executed.  This is
      * a <a href="package-summary.html#StreamOps">stateful intermediate operation</a>.
+     * @return the new stream
      */
     Stream<T> sorted();
 
@@ -197,6 +209,7 @@
      * {@code Comparator}.  This is
      * a <a href="package-summary.html#StreamOps">stateful intermediate operation</a>.
      * @param comparator A {@code Comparator} to be used to compare stream elements
+     * @return the new stream
      */
     Stream<T> sorted(Comparator<? super T> comparator);
 
@@ -251,6 +264,7 @@
      * it is responsible for providing the required synchronization.
      *
      * @param consumer The {@code Consumer} to receive the elements
+     * @return the new stream
      */
     Stream<T> peek(Consumer<? super T> consumer);
 
@@ -260,6 +274,7 @@
      * a <a href="package-summary.html#StreamOps">short-circuiting stateful intermediate operation</a>.
      *
      * @param maxSize the number elements the stream should be limited to.
+     * @return the new stream
      */
     Stream<T> limit(long maxSize);
 
@@ -269,6 +284,7 @@
      * a <a href="package-summary.html#StreamOps">stateful intermediate operation</a>.
      *
      * @param startingOffset the number of elements to be skipped.
+     * @return the new stream
      */
     Stream<T> substream(long startingOffset);
 
@@ -279,6 +295,7 @@
      *
      * @param startingOffset the starting position of the substream, inclusive
      * @param endingOffset the ending position of the substream, exclusive
+     * @return the new stream
      */
     Stream<T> substream(long startingOffset, long endingOffset);
 
@@ -433,7 +450,7 @@
      * @apiNote There are many existing classes in the JDK whose signatures are a good match for use as
      * arguments to {@code collect()}.  For example, the following will accumulate strings into an ArrayList:
      * <pre>
-     *     List<String> asList = stringStream.collect(ArrayList::new, ArrayList::add, ArrayList::addAll);
+     *     List&lt;String> asList = stringStream.collect(ArrayList::new, ArrayList::add, ArrayList::addAll);
      * </pre>
      *
      * The following will take a stream of strings and concatenates them into a single string:
@@ -462,19 +479,19 @@
      * @apiNote
      * The following will accumulate strings into an ArrayList:
      * <pre>
-     *     List<String> asList = stringStream.collect(Collectors.toList());
-     * </pre>
+     *     List&lt;String> asList = stringStream.collect(Collectors.toList());
+     * }</pre>
      *
      * The following will classify {@code Person} objects by city:
      * <pre>
-     *     Map<String, Collection<Person>> peopleByCity
+     *     Map&lt;String, Collection&lt;Person>> peopleByCity
      *         = personStream.collect(Collectors.groupBy(Person::getCity));
      * </pre>
      *
      * The following will classify {@code Person} objects by state and city, cascading two {@code Collector}s
      * together:
      * <pre>
-     *     Map<String, Map<String, Collection<Person>>> peopleByStateAndCity
+     *     Map&lt;String, Map&lt;String, Collection&lt;Person>>> peopleByStateAndCity
      *         = personStream.collect(Collectors.groupBy(Person::getState,
      *                                                   Collectors.groupBy(Person::getCity)));
      * </pre>

--- a/src/share/classes/java/util/stream/Streams.java	Fri Feb 22 17:51:40 2013 -0500
+++ b/src/share/classes/java/util/stream/Streams.java	Fri Feb 22 18:25:12 2013 -0500
@@ -202,9 +202,9 @@
      * <p>
      * @implSpec
      * The implementation behaves as if:
-     * <pre>{@code
-     *     intRange(start, end, start <= end ? 1 : -1);
-     * }</pre>
+     * <pre>
+     *     intRange(start, end, start &lt;= end ? 1 : -1);
+     * </pre>
      *
      * @param start the (inclusive) initial value
      * @param end the exclusive upper bound
@@ -224,9 +224,9 @@
      * an empty stream is returned.
      * <p>
      * An equivalent sequence of increasing values can be produced, sequentially, using a {@code for} loop as follows:
-     * <pre>{@code
-     *     for (int i = start; i < end ; i += step) { ... }
-     * }</pre>
+     * <pre>
+     *     for (int i = start; i &lt; end ; i += step) { ... }
+     * </pre>
      *
      * @param start the (inclusive) initial value
      * @param end the exclusive upper bound
@@ -280,10 +280,9 @@
      * <p>
      * @implSpec
      * The implementation behaves as if:
-     * <pre>{@code
-     *     longRange(start, end, start <= end ? 1 : -1);
+     * <pre>
+     *     longRange(start, end, start &lt;= end ? 1 : -1);
      * </pre>
-     * }
      *
      * @param start the (inclusive) initial value
      * @param end the exclusive upper bound
@@ -303,9 +302,9 @@
      * an empty stream is returned.
      * <p>
      * An equivalent sequence of increasing values can be produced, sequentially, using a {@code for} loop as follows:
-     * <pre>{@code
-     *     for (long i = start; i < end ; i += step) { ... }
-     * }</pre>
+     * <pre>
+     *     for (long i = start; i &lt; end ; i += step) { ... }
+     * </pre>
      *
      * @param start the (inclusive) initial value
      * @param end the exclusive upper bound

--- a/src/share/classes/java/util/stream/package-info.java	Fri Feb 22 17:51:40 2013 -0500
+++ b/src/share/classes/java/util/stream/package-info.java	Fri Feb 22 18:25:12 2013 -0500
@@ -76,7 +76,7 @@
  * <p>Terminal operations consume the {@code Stream} and produce a result or a side-effect.  After a terminal
  * operation is performed, the stream can no longer be used.
  *
- * <h3 name="StreamOps">Stream operations</h3>
+ * <h3><a name="StreamOps">Stream operations</a></h3>
  *
  * <p>Stream operations are divided into two categories: <em>intermediate</em> and <em>terminal</em>.  An
  * intermediate operation (such as {@code filter} or {@code sorted}) produces a new {@code Stream}; a terminal
@@ -134,7 +134,7 @@
  * serial equivalent, it is important to ensure that the function values passed into the various
  * stream operations be <em>non-interfering</em>.
  *
- * <a name="Ordering"><h3>Ordering</h3></a>
+ * <h3><a name="Ordering">Ordering</a></h3>
  *
  * <p>Streams may or may not have an <em>encounter order</em>.  Whether or not there is an encounter order
  * depends on the source, the intermediate operations, and the terminal operation.  Certain stream sources