RFR: 8365898: Specification of java.lang.module.ModuleDescriptor.packages() method can be improved [v2]

[Jaikiran Pai]

On Mon, 25 Aug 2025 16:50:18 GMT, Alan Bateman <alanb at openjdk.org> wrote:

>> Jaikiran Pai has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Chen's and Alan's review
>
> src/java.base/share/classes/java/lang/module/ModuleDescriptor.java line 1519:
> 
>> 1517: 
>> 1518:     /**
>> 1519:      * Returns the set of all packages in the module.
> 
> We changed this from "Returns the names of all packages in this module" to "Returns the set of packages in the module" as part of JDK-8173393 in JDK 9 [1]. This was a large update and I can't recall if there was a reason to drop "all" at the time. Looking at the API docs now, I think it's useful to say "all packages".  It can use `{@return ..}` as Chen suggests. I think it might be clearer if we just dropped the second paragraph, it's not needed. (I think this second paragraph may date when when there was a method to get the concealed/non-exported packages).
> 
> [1] https://hg.openjdk.org/jdk9/jdk9/jdk/rev/1c8f054f6278

Thank you Alan for finding this history. I have now updated the PR to remove the second paragraph and also follow Chen's and your suggestion about the `{@return ...}` usage.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/26928#discussion_r2299430933