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

[Jaikiran Pai]

On Tue, 26 Aug 2025 05:18:00 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:      * {@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.

I've now updated the PR to follow this suggestion. The second paragraph has been removed as suggested and I haven't done any changes to the existing `@return` tag. If necessary I can adjust the text further.

This now renders as:

<img width="651" height="196" alt="packages" src="https://github.com/user-attachments/assets/60ad1584-73d1-4c71-8258-3bcb130cf916" />

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

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