Specs

[Joe Bowbeer]

FWIW, I made the same point about docs duplication.

All five stream interfaces (BaseStream, DoubleStream, IntStream,
LongStream, and Stream) appear with an identical description in the class
overview:

http://cr.openjdk.java.net/~briangoetz/doctmp/doc1/

Furthermore, there is no distinction in the javadoc between the base
interface BaseStream, which is not something programmers will tend to use,
and the four subinterfaces that will be commonly used.

--Joe


On Tue, Sep 3, 2013 at 7:46 PM, Mike Duigou <mike.duigou at oracle.com> wrote:

> 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?
> >>
> >>
> >>
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.openjdk.java.net/pipermail/lambda-libs-spec-experts/attachments/20130903/c83a5b48/attachment-0001.html