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

[Alan Bateman]

On 03/03/2015 18:16, Stuart Marks wrote:
> On 3/3/15 5:42 AM, Alan Bateman wrote:
>> 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.
That would be good, thanks.


> :
>
> 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.
It's a testable with custom file system provider or if you interpose on 
the default provider, but not easy. If methods such as lines specify 
that they need a reference to an open file then I think it should be 
okay for list/walk to specify that they keep a reference to the open 
directory (or directories). That would allow you to drop any reference 
to DirectoryStream, except perhaps @see or @implNote.

-Alan