RFR: 8290353: Clarify the streams returned by ModuleReader::list

[Mandy Chung]

On Mon, 18 Jul 2022 14:53:19 GMT, Chris Hegarty <chegar at openjdk.org> wrote:

>> This commit adds additional clarification to the javadocs of
>> ModuleReader::list about needing to close the stream. The new wording is
>> similar to that used in Files::find and other similar methods.
>
> src/java.base/share/classes/java/lang/module/ModuleReader.java line 217:
> 
>> 215:      *
>> 216:      * <p> The returned stream contains references to one or more open directories
>> 217:      * in the module. The directories are closed by closing the stream. </p>
> 
> This mostly looks good - I agree with adding the note here. Should the wording be relaxed a little - replace "contains references" with "may contain references" - since the stream will not always contain references to open directories - it depends on the type of reader. The end result / guidance is the same - use in a try-with-resources block - I'm just suggesting a slight relaxing of the wording.

"may contain references" is good.   I agree that the wordings should be relaxed a little.  Similar for the apiNote.

-------------

PR: https://git.openjdk.org/jdk/pull/9538