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

[Stuart Marks]

On 3/3/15 12:27 PM, Alan Bateman wrote:
> 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.

Changed.

>> 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.

Hm, yes, it is rather strange for the docs to reference DirectoryStream 
specifically, when the point is not this specific class, but more the abstract 
concept of an open resource. I've reworded the clauses to remove mentions of the 
specific DirectoryStream class, and I've replaced the mentions with wording such 
as "references to one or more open files."

Updated webrev:

     http://cr.openjdk.java.net/~smarks/reviews/8073923/webrev.2/

s'marks