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

[Sam Brannen]

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

>> Hmm. I'll consider that. The javadoc in java.lang.Class is inconsistent in the formatting of "void" as a type name, some instances are in code markup while others are not.
>
>> @jddarcy and @pavelrappo, as I understood it, @liach is not suggesting that the term "void" in "primitive types and void" should be replaced by `{@code void}`.
>> 
>> Rather, `{@code void}` should be included in the enumeration of primitive types -- for example, by replacing `and {@code double}` with `{@code double}, and {@code void}`.
> 
> AFAIK, that sentence enumerates primitive types, which according to the Java Language Specification [^1][^2], do not include `void`.
> 
> [^1]: https://docs.oracle.com/javase/specs/jls/se20/html/jls-4.html#jls-4.2
> [^2]: https://docs.oracle.com/javase/specs/jls/se20/html/jls-8.html#jls-8.4.5

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."

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

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