Specs

[Brian Goetz]

Thanks Stephen.  Applied most of these.

Where I think the biggest challenge is in specifying this package is the 
unfortunately dense ball of concepts required to really internalize how 
its supposed to be used.  For example, you won't get the best results 
until you understand:
  - laziness
  - reduction
  - non-interference
  - statelessness
  - encounter order
  - parallelism

That's a lot!  So, my big concern is that this doc is missing something 
that will help people get how these concepts come together in this 
library.


On 8/29/2013 8:18 AM, Stephen Colebourne wrote:
> 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?
>>
>