RFR: JDK-8310267: Javadoc for Class#isPrimitive() is incorrect regarding Class objects for primitives [v2]

[Joe Darcy]

On Fri, 23 Jun 2023 11:58:00 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> Thanks for the links, @pavelrappo.
>> 
>> I understand the point you're making; however, there is still ambiguous wording in the documentation for this method.
>> 
>> The method is called `isPrimitive`, and it returns `true` for `isPrimitive(void.class)`. In addition, the first sentence states: "Determines if the specified `Class` object represents a primitive type."
>> 
>> Note as well that the documentation states "There are nine predefined ..." but then goes on to only list 8 names.
>> 
>> So, in line with the intent of the method with regard to `void`, it should be clear to the user that `void` is the name for the type `void.class` (and `Void.TYPE`).
>> 
>> Perhaps the easiest way to include `void.class` and match the 9 predefined types with their names is to remove "primitive" from "as the primitive types that" and replace `and {@code double}` with `{@code double}, and {@code void}`.
>> 
>> Along that line of thinking, it might be best to change the first sentence to "Determines if the specified `Class` object represents a primitive type or void." And the return statement should be changed to `@return true if and only if this class represents a primitive type or void`.
>
>> Along that line of thinking, it might be best to change the first sentence to "Determines if the specified Class object represents a primitive type or void."
> 
> I was just about to suggest exactly that, but from the superinterface method's perspective. Here's what I had been writing when received your message:
> 
> At the same, time java.lang.invoke.TypeDescriptor.OfField#isPrimitive:
> 
>         /**
>          * Does this field descriptor describe a primitive type (including void.)
>          *
>          * @return whether this field descriptor describes a primitive type
>          */
>         boolean isPrimitive();
> 
> I suggest rephrasing that and similar text elsewhere, for example, as follows:
> 
>     /** {@return whether this field descriptor describes a primitive type or void} */
>     boolean isPrimitive();

The functionality of the method is "isPrimitiveTypeOrVoid" as void is technically not a type, etc.; however, the method is named "isPrimitive" and that is most of what it does.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/14574#discussion_r1240093494