Specs

[Stephen Colebourne]

Review of http://cr.openjdk.java.net/~briangoetz/doctmp/doc/java/util/stream/package-summary.html

HTML <code> appears in a number of places as text in the output javadoc

Second bulleted list should include "static methods on Stream, for example..."

Using ** to highlight changes:
"Stream operations are divided into intermediate and terminal
operations. Intermediate operations are further divided into stateless
and stateful operations. **new-para

Stateless **intermediate operations retain no state from previously
seen values when processing a new value.**For example, filter and map.
Stateful **intermediate operations may incorporate state from
previously seen elements in processing new values. **For example,
distinct and sorted. Stateful operations may need to process the
entire input before producing a result; for example, one cannot
produce any results from sorting a stream until one has seen all
elements of the stream. As a result, under parallel computation, some
pipelines containing stateful intermediate operations have to be
executed in multiple passes or may need to buffer significant data.
Pipelines containing exclusively stateless intermediate operations can
be processed in a single pass, whether sequential or parallel, with
minimal data buffering. "

"With the exception of the iterator() and spliterator() terminal
operations (which are provided as an "escape hatch" to enable
arbitrary stream traversals in the event that the existing operations
are not sufficient to the task), terminal operations are always eager,
executing completely before returning. "
better reversed as:
"Terminal operations are almost always eager, executing completely
before returning. Only the terminal operations iterator() and
spliterator() are not, and they are provided solely as an "escape
hatch" to enable arbitrary stream traversals in the event that the
existing operations are not sufficient to the task."

Remove brackets:
"Except for operations identified as explicitly nondeterministic,
**such as findAny(), whether a stream executes sequentially or in
parallel should not change the result of the computation. "

Remove brackets:
"**Except for the escape-hatch methods...

"then any of the six permutations of the values [2, 4, 6] would be a
valid result. "
change to
"then [6, 2, 4 ] or any of the other permutations of the values would
be a valid result. "

" (An ArrayList is constrained to iterate elements in order; a HashSet
is not, and repeated iteration might produce a different order.) "
change to
" For example, an ArrayList is constrained to iterate elements in
order; a HashSet is not, and repeated iteration might produce a
different order."


Reduction/Multable reduction sections feel like they would in a book,
rather than Javadoc. In a book, you take people on a journey from old
to new. In Javadoc, I'd expect to see the preferred end result first,
driling down into the next level of detail, then the most complex. I'd
recommend significant reflowing.

Title "Reduction, Concurrency, and Ordering" could be "Concurrent reduction"

Associativity needs an example of an associative operator.

Hope this helps
Stephen












On 28 August 2013 22:58, Brian Goetz <brian.goetz at oracle.com> wrote:
> Have I mentioned that reviews of the specs and package doc at:
>
>   http://cr.openjdk.java.net/~briangoetz/doctmp/doc/
>
> would be appreciated?
>