RFR: JDK-8292576: Improve wording of AccessFlag-related specs

[Alan Bateman]

On Thu, 18 Aug 2022 18:16:21 GMT, Joe Darcy <darcy at openjdk.org> wrote:

>> src/java.base/share/classes/java/lang/module/ModuleDescriptor.java line 217:
>> 
>>> 215:         /**
>>> 216:          * {@return an unmodifiable set of the module {@linkplain AccessFlag
>>> 217:          * requires flags}, possibly empty}
>> 
>> The link fix looks okay but the wording in the new accessFlags() method is different to the wording in the other methods. The other methods use "possibly-empty unmodifiable" in the return description. Either is fine but I think we should try to keep the wording consistent where possible.
>
> I've looked over the wording of the various accessFlags methods. The wording for ModuleDescriptor.Requires looks consistent to me:
> 
> Returns an unmodifiable set of the module flags, possibly empty.
> 
> Returns an unmodifiable set of the module export flags for this module descriptor, possibly empty.
> 
> Returns an unmodifiable set of the module opens flags, possibly empty.
> 
> Returns an unmodifiable set of the module requires flags, possibly empty.
> 
> ----
> 
> Returns an unmodifiable set of the access flags for this class, possibly empty.
> 
> Returns an unmodifiable set of the access flags for the executable represented by this object, possibly empty.
> 
> Returns an unmodifiable set of the access flags for this member, possibly empty.
> 
> Returns an unmodifiable set of the access flags for the parameter represented by this object, possibly empty.
> 
> Am I overlooking something in the twisty passages, all alike?

If you compare the javadoc for the modifiers vs. accessFlags in each of ModuleDescriptor, Requires, Exports, and Opens then you'll see what I mean. I was hoping they could be inconsistent.

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

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