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

[Alan Bateman]

On Tue, 26 Aug 2025 00:42:52 GMT, Jaikiran Pai <jpai at openjdk.org> wrote:

>> Can I please get a review of this trivial change to the `ModuleDescriptor.packages()` method's specification?
>> 
>> The change here clarifies that this method returns all packages that belong to the module and not just those that are exported or open. This clarification should help avoid any confusion that may have been caused by the second paragraph in that method's specification which talks about exported and open packages.
>> 
>> This updated specification matches the existing implementation of this method.
>> 
>> I believe this will require a CSR, which I'll create shortly.
>
> 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:      * {@return a possibly-empty unmodifiable set of all packages in the module}

On second thoughts, having "possibly-empty unmodifiable set" in the first sentence of the method description will be inconsistent with all the other method descriptions. If you scan the descriptions of the other methods then you'll see they have a simple/clear first line, the "possibly-empty unmodifiable set" is in the return description. Sorry for the flip-flop, I think it will be clearer to just say "Returns the set of all packages in the module." as the first sentence.

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

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