mike.duigou at oracle.com
Tue Sep 3 19:46:21 PDT 2013
- 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"
- "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.
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:
> 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.)
>> 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.
>> 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:
>> would be appreciated?
More information about the lambda-libs-spec-observers