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

[Chris Hegarty]

On Mon, 18 Jul 2022 14:06:00 GMT, Ryan Ernst <duke 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.

src/java.base/share/classes/java/lang/module/ModuleReader.java line 224:

> 222:      * @apiNote
> 223:      * This method must be used within a try-with-resources statement or similar
> 224:      * control structure to ensure that the stream's open directories are closed

Similar to my other comment - should "must' be replaced with "should" - for the same aforementioned reason.

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

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