On Fri, 24 May 2024 15:50:00 GMT, Chris Plummer <cjplum...@openjdk.org> wrote:
>> src/java.management.rmi/share/classes/javax/management/remote/rmi/RMIConnection.java
>> line 961:
>>
>>> 959: * @param delegationSubjects should be {@code null}, but a non-null
>>> 960: * array is also accepted for compatibility reasons, which must not
>>> 961: * contain any non-null entries.
>>
>> The wording is bit unusual for a parameter description. Just wondering if
>> might be clearer to say "null or an array of null elements" and put add an
>> `@apiNote` to explain that it allows an array with null elements for
>> compatibility reasons. What you have is okay too course, I'm just trying to
>> think of another way to present this odd case.
>
> How about "must be null or an array of all null entries". You could still
> have an `@apiNote` explaining why.
Thanks, appreciate the effort trying to make it perfect.
Can't quite say "must be null or an array of all null entries" ..because I
suppose it could be an empty array.
In reality, the only caller is our code that wraps a null Subject value, in an
array, so it's generally a single null in an array.
I hope we are OK sticking with "which must not contain any non-null entries" as
that does cover it (and implicitly does tell you an empty array is fine).
-------------
PR Review Comment: https://git.openjdk.org/jdk/pull/19253#discussion_r1613758498
