Specs

[Mike Duigou]

Stream::
- The docs duplication between the stream flavours still bothers me. Can we call out the per-flavour differences in some succinct way? If there is anything subtle in the class docs between flavours I am certain most people would miss it.

- Could the description of stream pipeline be broken into a definition list of the parts? 

- Stream source isn't distinguished as a term in the pipeline description.

- "since some stream operations may return their receiver rather than a new stream object," I would move this to a separate sentence or move the "it may not be possible to detect reuse in all cases." to the previous sentence.

- link to BaseStream.close() should be just close().

- "whose source is an IO channel" IO -> I/O

-  Replace parenthetical comment "(If a stream does require closing, it can be declared as a resource in a try-with-resources statement.)" with an example.

- Method links to sequential(), parallel() and isParallel() should use simple form (without BaseStream)

- Link to "effectively stateless" to "package-summary.html#NonInterference" should be "package-summary.html#Non-Interference"

package-info::

- "Streams differ from collections in several ways:" use a definition list to highlight the key points?

- "Streams can be obtained in a number of ways" -> "Streams can be obtained from many sources". Reinforce "source"
- "Stream operations and pipelines"
   - The intial link to itself in first sentence is redundant.
   - that stream operations are described as being "divided and combined" is possibly confusing since they refer to different things--one might think that a pipeline has one intermediate and one terminal operations. Perhaps just remove the first sentence.


I can apply any of these to the source if you would prefer.

Mike

On Sep 3 2013, at 11:37 , Brian Goetz wrote:

> Plowing through all of these today...I've got just about all the directly actionable ones processed, stumbling a bit on the less actionable ones (e.g., "This section needs work.")
> 
> I've updated the docs at the temporary site.
> 
> Old docs: http://cr.openjdk.java.net/~briangoetz/doctmp/doc0
> New docs: http://cr.openjdk.java.net/~briangoetz/doctmp/doc1
> 
> And posted a "specdiff" between them at:
>  http://cr.openjdk.java.net/~briangoetz/doctmp/diff1


> 
> 
> 
> 
> On 9/2/2013 2:42 PM, Tim Peierls wrote:
>> I sent Brian comments on the package summary a couple of days ago. I am
>> curious to see whether there's any overlap or disagreement between what
>> Joe wrote and what I wrote, but I'm sort of hoping Brian will summarize
>> all of the responses rather than having to wade through them myself.
>> (Yes, I know that just adds to Brian's work pile, but some sort of
>> summary will be needed in any case.)
>> 
>> --tim
>> 
>> 
>> On Mon, Sep 2, 2013 at 12:15 PM, Joe Bowbeer <joe.bowbeer at gmail.com
>> <mailto:joe.bowbeer at gmail.com>> wrote:
>> 
>>    I just sent Brian comments on the package description and the
>>    BaseStream family of interfaces.
>> 
>>    Overall, I like the way this is coming together.  The package
>>    description is substantial, but it's worth the programmer's time.
>>      The references to package-description in the Stream methods are
>>    effective.  Hey, I *feel* like I understand.
>> 
>>    However, there's plenty of room for improvement.  I'd be happy to
>>    send my detailed review - or a simplified summary - to this list if
>>    there is interest.
>> 
>>    --Joe
>> 
>> 
>>    On Wed, Aug 28, 2013 at 2:58 PM, Brian Goetz <brian.goetz at oracle.com
>>    <mailto: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/
>>        <http://cr.openjdk.java.net/~briangoetz/doctmp/doc/>
>> 
>>        would be appreciated?
>> 
>> 
>>