RFR(s): 8073923: Files.lines() documentation needs clarification

[Stuart Marks]

On 3/3/15 5:42 AM, Alan Bateman wrote:
> On 03/03/2015 02:43, Stuart Marks wrote:
>> Oh yes, good point. Revised webrev:
>>
>>     http://cr.openjdk.java.net/~smarks/reviews/8073923/webrev.1/
>>
> One small quibble is "contains an open file" as it's really that the stream has
> a reference to an open file.

True. I can change this if you like.

> The other thing is the list and walk methods where it specifies that the
> returned stream encapsulates one or more DirectoryStream object, a point that
> could be downgraded to an implementation note. It is of course important to make
> it clear that these methods return a stream that has references to open
> directories.

Yeah, it was a little uncomfortable leaving the "contains one or more 
DirectoryStreams" where it was, and separating the @apiNote recommending use of 
try-with-resources. But I did so deliberately, because the statement about 
containing a DirectoryStream (or open file) that is closed by the closed() call 
is a normative part of the spec, and indeed it's testable. (I don't know whether 
in fact it is tested though.) I didn't think that it belonged in the @apiNote.

s'marks