From 5586f83e34c2fe0bdc48daef8c456678cea55af1 Mon Sep 17 00:00:00 2001 From: Joe Darcy Date: Mon, 30 Sep 2024 16:13:35 +0000 Subject: [PATCH] 8341064: Define anchor point and index term for "wrapper classes" Reviewed-by: prappo, liach --- .../share/classes/java/lang/Boolean.java | 10 ++-- .../share/classes/java/lang/Byte.java | 10 ++-- .../share/classes/java/lang/Character.java | 14 +++--- .../share/classes/java/lang/Double.java | 8 +-- .../share/classes/java/lang/Float.java | 8 +-- .../share/classes/java/lang/Integer.java | 7 +-- .../share/classes/java/lang/Long.java | 5 +- .../share/classes/java/lang/Short.java | 7 +-- .../share/classes/java/lang/package-info.java | 49 +++++++++++-------- .../classes/javax/lang/model/util/Types.java | 5 +- 10 files changed, 67 insertions(+), 56 deletions(-) diff --git a/src/java.base/share/classes/java/lang/Boolean.java b/src/java.base/share/classes/java/lang/Boolean.java index ba88157dc92..2c0925a9790 100644 --- a/src/java.base/share/classes/java/lang/Boolean.java +++ b/src/java.base/share/classes/java/lang/Boolean.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1994, 2021, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1994, 2024, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -37,10 +37,10 @@ import static java.lang.constant.ConstantDescs.BSM_GET_STATIC_FINAL; import static java.lang.constant.ConstantDescs.CD_Boolean; /** - * The Boolean class wraps a value of the primitive type - * {@code boolean} in an object. An object of type - * {@code Boolean} contains a single field whose type is - * {@code boolean}. + * The {@code Boolean} class is the {@linkplain + * java.lang##wrapperClass wrapper class} for values of the primitive + * type {@code boolean}. An object of type {@code Boolean} contains a + * single field whose type is {@code boolean}. * *

In addition, this class provides many methods for * converting a {@code boolean} to a {@code String} and a diff --git a/src/java.base/share/classes/java/lang/Byte.java b/src/java.base/share/classes/java/lang/Byte.java index 18502abf69c..ade75a7a99e 100644 --- a/src/java.base/share/classes/java/lang/Byte.java +++ b/src/java.base/share/classes/java/lang/Byte.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1996, 2023, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1996, 2024, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -39,10 +39,10 @@ import static java.lang.constant.ConstantDescs.CD_int; import static java.lang.constant.ConstantDescs.DEFAULT_NAME; /** - * - * The {@code Byte} class wraps a value of primitive type {@code byte} - * in an object. An object of type {@code Byte} contains a single - * field whose type is {@code byte}. + * The {@code Byte} class is the {@linkplain + * java.lang##wrapperClass wrapper class} for values of the primitive + * type {@code byte}. An object of type {@code Byte} contains a + * single field whose type is {@code byte}. * *

In addition, this class provides several methods for converting * a {@code byte} to a {@code String} and a {@code String} to a {@code diff --git a/src/java.base/share/classes/java/lang/Character.java b/src/java.base/share/classes/java/lang/Character.java index a829d71e113..84db550d7cc 100644 --- a/src/java.base/share/classes/java/lang/Character.java +++ b/src/java.base/share/classes/java/lang/Character.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2002, 2023, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2002, 2024, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -43,12 +43,12 @@ import static java.lang.constant.ConstantDescs.CD_char; import static java.lang.constant.ConstantDescs.DEFAULT_NAME; /** - * The {@code Character} class wraps a value of the primitive - * type {@code char} in an object. An object of class - * {@code Character} contains a single field whose type is - * {@code char}. - *

- * In addition, this class provides a large number of static methods for + * The {@code Character} class is the {@linkplain + * java.lang##wrapperClass wrapper class} for values of the primitive + * type {@code char}. An object of type {@code Character} contains a + * single field whose type is {@code char}. + * + *

In addition, this class provides a large number of static methods for * determining a character's category (lowercase letter, digit, etc.) * and for converting characters from uppercase to lowercase and vice * versa. diff --git a/src/java.base/share/classes/java/lang/Double.java b/src/java.base/share/classes/java/lang/Double.java index e789a677717..68fff6a2fbd 100644 --- a/src/java.base/share/classes/java/lang/Double.java +++ b/src/java.base/share/classes/java/lang/Double.java @@ -36,10 +36,10 @@ import jdk.internal.math.DoubleToDecimal; import jdk.internal.vm.annotation.IntrinsicCandidate; /** - * The {@code Double} class wraps a value of the primitive type - * {@code double} in an object. An object of type - * {@code Double} contains a single field whose type is - * {@code double}. + * The {@code Double} class is the {@linkplain + * java.lang##wrapperClass wrapper class} for values of the primitive + * type {@code double}. An object of type {@code Double} contains a + * single field whose type is {@code double}. * *

In addition, this class provides several methods for converting a * {@code double} to a {@code String} and a diff --git a/src/java.base/share/classes/java/lang/Float.java b/src/java.base/share/classes/java/lang/Float.java index 02b66007773..470eb71cf70 100644 --- a/src/java.base/share/classes/java/lang/Float.java +++ b/src/java.base/share/classes/java/lang/Float.java @@ -36,10 +36,10 @@ import jdk.internal.math.FloatToDecimal; import jdk.internal.vm.annotation.IntrinsicCandidate; /** - * The {@code Float} class wraps a value of primitive type - * {@code float} in an object. An object of type - * {@code Float} contains a single field whose type is - * {@code float}. + * The {@code Float} class is the {@linkplain + * java.lang##wrapperClass wrapper class} for values of the primitive + * type {@code float}. An object of type {@code Float} contains a + * single field whose type is {@code float}. * *

In addition, this class provides several methods for converting a * {@code float} to a {@code String} and a diff --git a/src/java.base/share/classes/java/lang/Integer.java b/src/java.base/share/classes/java/lang/Integer.java index fccdd697c72..eab0a942d9a 100644 --- a/src/java.base/share/classes/java/lang/Integer.java +++ b/src/java.base/share/classes/java/lang/Integer.java @@ -45,9 +45,10 @@ import static java.lang.String.LATIN1; import static java.lang.String.UTF16; /** - * The {@code Integer} class wraps a value of the primitive type - * {@code int} in an object. An object of type {@code Integer} - * contains a single field whose type is {@code int}. + * The {@code Integer} class is the {@linkplain + * java.lang##wrapperClass wrapper class} for values of the primitive + * type {@code int}. An object of type {@code Integer} contains a + * single field whose type is {@code int}. * *

In addition, this class provides several methods for converting * an {@code int} to a {@code String} and a {@code String} to an diff --git a/src/java.base/share/classes/java/lang/Long.java b/src/java.base/share/classes/java/lang/Long.java index ff34da232f9..f86e1622b38 100644 --- a/src/java.base/share/classes/java/lang/Long.java +++ b/src/java.base/share/classes/java/lang/Long.java @@ -45,8 +45,9 @@ import static java.lang.String.LATIN1; import static java.lang.String.UTF16; /** - * The {@code Long} class wraps a value of the primitive type {@code - * long} in an object. An object of type {@code Long} contains a + * The {@code Long} class is the {@linkplain + * java.lang##wrapperClass wrapper class} for values of the primitive + * type {@code long}. An object of type {@code Long} contains a * single field whose type is {@code long}. * *

In addition, this class provides several methods for converting diff --git a/src/java.base/share/classes/java/lang/Short.java b/src/java.base/share/classes/java/lang/Short.java index 6a148d1edac..ec792de47e2 100644 --- a/src/java.base/share/classes/java/lang/Short.java +++ b/src/java.base/share/classes/java/lang/Short.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1996, 2023, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1996, 2024, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -39,8 +39,9 @@ import static java.lang.constant.ConstantDescs.CD_short; import static java.lang.constant.ConstantDescs.DEFAULT_NAME; /** - * The {@code Short} class wraps a value of primitive type {@code - * short} in an object. An object of type {@code Short} contains a + * The {@code Short} class is the {@linkplain + * java.lang##wrapperClass wrapper class} for values of the primitive + * type {@code short}. An object of type {@code Short} contains a * single field whose type is {@code short}. * *

In addition, this class provides several methods for converting diff --git a/src/java.base/share/classes/java/lang/package-info.java b/src/java.base/share/classes/java/lang/package-info.java index 882a610c1a0..0484ecb2952 100644 --- a/src/java.base/share/classes/java/lang/package-info.java +++ b/src/java.base/share/classes/java/lang/package-info.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1998, 2018, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1998, 2024, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -25,35 +25,42 @@ /** * Provides classes that are fundamental to the design of the Java - * programming language. The most important classes are {@code - * Object}, which is the root of the class hierarchy, and {@code + * programming language. The most important classes are {@link + * Object}, which is the root of the class hierarchy, and {@link * Class}, instances of which represent classes at run time. * *

Frequently it is necessary to represent a value of primitive - * type as if it were an object. The wrapper classes {@code Boolean}, - * {@code Character}, {@code Integer}, {@code Long}, {@code Float}, - * and {@code Double} serve this purpose. An object of type {@code - * Double}, for example, contains a field whose type is double, - * representing that value in such a way that a reference to it can be - * stored in a variable of reference type. These classes also provide - * a number of methods for converting among primitive values, as well - * as supporting such standard methods as equals and hashCode. The - * {@code Void} class is a non-instantiable class that holds a - * reference to a {@code Class} object representing the type void. + * type as if it were an object.The {@index + * "wrapper classes"} {@link Boolean}, {@link Byte}, {@link + * Character}, {@link Short}, {@link Integer}, {@link Long}, {@link + * Float}, and {@link Double} serve this purpose. An object of type + * {@code Double}, for example, contains a field whose type is {@code + * double}, representing that value in such a way that a reference to + * it can be stored in a variable of reference type. As discussed in + * The Java Language Specification, the wrapper classes + * are involved in boxing (JLS {@jls 5.1.7}) and unboxing (JLS {@jls + * 5.1.8}) conversions. These classes provide a number of methods for + * converting among primitive values, as well as methods supporting + * such standard functionality as {@code equals} and {@code hashCode}. + * The {@link Void} class is a non-instantiable class that holds a + * reference to a {@code Class} object representing the type {@code + * void}. * - *

The class {@code Math} provides commonly used mathematical - * functions such as sine, cosine, and square root. The classes {@code - * String}, {@code StringBuffer}, and {@code StringBuilder} similarly - * provide commonly used operations on character strings. + *

The class {@link Math} provides commonly used mathematical + * functions such as {@linkplain Math#sin(double) sine}, {@linkplain + * Math#cos(double) cosine}, and {@linkplain Math#sqrt(double) square + * root}. The classes {@link String}, {@link StringBuffer}, and {@link + * StringBuilder} similarly provide commonly used operations on + * character strings. * - *

Classes {@code ClassLoader}, {@code Process}, {@code - * ProcessBuilder}, {@code Runtime}, {@code SecurityManager}, and - * {@code System} provide "system operations" that manage the dynamic + *

Classes {@link ClassLoader}, {@link Process}, {@link + * ProcessBuilder}, {@link Runtime}, {@link SecurityManager}, and + * {@link System} provide "system operations" that manage the dynamic * loading of classes, creation of external processes, host * environment inquiries such as the time of day, and enforcement of * security policies. * - *

Class {@code Throwable} encompasses objects that may be thrown + *

Class {@link Throwable} encompasses objects that may be thrown * by the {@code throw} statement. Subclasses of {@code Throwable} * represent errors and exceptions. * diff --git a/src/java.compiler/share/classes/javax/lang/model/util/Types.java b/src/java.compiler/share/classes/javax/lang/model/util/Types.java index 232e15a84bd..ce83cda4058 100644 --- a/src/java.compiler/share/classes/javax/lang/model/util/Types.java +++ b/src/java.compiler/share/classes/javax/lang/model/util/Types.java @@ -205,8 +205,9 @@ public interface Types { * @return the type of an unboxed value of type {@code t} * * @throws IllegalArgumentException if the given type has no - * unboxing conversion. Only types for the wrapper classes - * have an unboxing conversion. + * unboxing conversion. Only types for the {@linkplain + * java.lang##wrapperClasses wrapper classes} have an + * unboxing conversion. * @jls 5.1.8 Unboxing Conversion */ PrimitiveType unboxedType(TypeMirror t);