8290353: ModuleReader::list specification should suggest closing the returned stream

Reviewed-by: chegar, mchung, mr, jpai

Author: rjernst

src/java.base/share/classes/java/lang/module/ModuleReader.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2015, 2020, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2015, 2022, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -213,9 +213,17 @@ default void release(ByteBuffer bb) {
  * when using the stream to list the module contents and access is denied
  * by the security manager. </p>
  *
+ * <p> The returned stream may contain references to one or more open directories
+ * in the module. The directories are closed by closing the stream. </p>
+ *
  * <p> The behavior of the stream when used after the module reader is
  * closed is implementation specific and therefore not specified. </p>
  *
+ * @apiNote
+ * This method should be used within a try-with-resources statement or similar
+ * control structure to ensure that any open directories referenced by the
+ * stream are closed promptly after the stream's operations have completed.
+ *
  * @return A stream of elements that are the names of all resources
  * in the module
  *