stan/jdk-24
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

8017550: Fix doclint issues in java.lang and subpackages

Browse Source 
Reviewed-by: alanb, chegar
This commit is contained in:
Joe Darcy 2013-06-24 23:40:31 -07:00
parent 9c0605b8e6
commit e751cc77ad
22 changed files with 101 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
jdk/src/share/classes/java/lang/Boolean.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 1994, 2011, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 1994, 2013, 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
@ -205,9 +205,9 @@ public final class Boolean implements java.io.Serializable,
* Returns a hash code for a {@code boolean} value; compatible with
* {@code Boolean.hashCode()}.
*
* @since 1.8
*
* @param value the value to hash
* @return a hash code value for a {@code boolean} value.
* @since 1.8
*/
public static int hashCode(boolean value) {
return value ? 1231 : 1237;

6
jdk/src/share/classes/java/lang/Byte.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 1996, 2012, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 1996, 2013, 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
@ -398,9 +398,9 @@ public final class Byte extends Number implements Comparable<Byte> {
* Returns a hash code for a {@code byte} value; compatible with
* {@code Byte.hashCode()}.
*
* @since 1.8
*
* @param value the value to hash
* @return a hash code value for a {@code byte} value.
* @since 1.8
*/
public static int hashCode(byte value) {
return (int)value;

4
jdk/src/share/classes/java/lang/Class.java
View File

@ -3250,6 +3250,8 @@ public final class Class<T> implements java.io.Serializable,
* could not be checked at runtime (because generic types are implemented
* by erasure).
*
* @param <U> the type to cast this class object to
* @param clazz the class of the type to cast this class object to
* @return this {@code Class} object, cast to represent a subclass of
* the specified class object.
* @throws ClassCastException if this {@code Class} object does not
@ -3405,6 +3407,7 @@ public final class Class<T> implements java.io.Serializable,
* If this Class represents either the Object class, an interface type, an
* array type, a primitive type, or void, the return value is null.
*
* @return an object representing the superclass
* @since 1.8
*/
public AnnotatedType getAnnotatedSuperclass() {
@ -3436,6 +3439,7 @@ public final class Class<T> implements java.io.Serializable,
* If this Class represents either the Object class, an array type, a
* primitive type, or void, the return value is an array of length 0.
*
* @return an array representing the superinterfaces
* @since 1.8
*/
public AnnotatedType[] getAnnotatedInterfaces() {

12
jdk/src/share/classes/java/lang/Double.java
View File

@ -453,8 +453,7 @@ public final class Double extends Number implements Comparable<Double> {
* a {@code NumberFormatException} be thrown, the regular
* expression below can be used to screen the input string:
*
* <code>
* <pre>
* <pre>{@code
* final String Digits = "(\\p{Digit}+)";
* final String HexDigits = "(\\p{XDigit}+)";
* // an exponent is 'e' or 'E' followed by an optionally
@ -474,7 +473,7 @@ public final class Double extends Number implements Comparable<Double> {
* // in addition to strings of floating-point literals, the
* // two sub-patterns below are simplifications of the grammar
* // productions from section 3.10.2 of
* // <cite>The Java&trade; Language Specification</cite>.
* // The Java Language Specification.
*
* // Digits ._opt Digits_opt ExponentPart_opt FloatTypeSuffix_opt
* "((("+Digits+"(\\.)?("+Digits+"?)("+Exp+")?)|"+
@ -499,8 +498,7 @@ public final class Double extends Number implements Comparable<Double> {
* else {
* // Perform suitable alternative action
* }
* </pre>
* </code>
* }</pre>
*
* @param s the string to be parsed.
* @return a {@code Double} object holding the value
@ -756,9 +754,9 @@ public final class Double extends Number implements Comparable<Double> {
* Returns a hash code for a {@code double} value; compatible with
* {@code Double.hashCode()}.
*
* @since 1.8
*
* @param value the value to hash
* @return a hash code value for a {@code double} value.
* @since 1.8
*/
public static int hashCode(double value) {
long bits = doubleToLongBits(value);

4
jdk/src/share/classes/java/lang/Float.java
View File

@ -664,9 +664,9 @@ public final class Float extends Number implements Comparable<Float> {
* Returns a hash code for a {@code float} value; compatible with
* {@code Float.hashCode()}.
*
* @since 1.8
*
* @param value the value to hash
* @return a hash code value for a {@code float} value.
* @since 1.8
*/
public static int hashCode(float value) {
return floatToIntBits(value);

13
jdk/src/share/classes/java/lang/Integer.java
View File

@ -951,6 +951,7 @@ public final class Integer extends Number implements Comparable<Integer> {
* Returns a hash code for a {@code int} value; compatible with
* {@code Integer.hashCode()}.
*
* @param value the value to hash
* @since 1.8
*
* @return a hash code value for a {@code int} value.
@ -1336,6 +1337,7 @@ public final class Integer extends Number implements Comparable<Integer> {
* one-bits in its two's complement binary representation, that is, if it
* is equal to zero.
*
* @param i the value whose highest one bit is to be computed
* @return an {@code int} value with a single one-bit, in the position
* of the highest-order one-bit in the specified value, or zero if
* the specified value is itself equal to zero.
@ -1358,6 +1360,7 @@ public final class Integer extends Number implements Comparable<Integer> {
* one-bits in its two's complement binary representation, that is, if it
* is equal to zero.
*
* @param i the value whose lowest one bit is to be computed
* @return an {@code int} value with a single one-bit, in the position
* of the lowest-order one-bit in the specified value, or zero if
* the specified value is itself equal to zero.
@ -1382,6 +1385,7 @@ public final class Integer extends Number implements Comparable<Integer> {
* <li>ceil(log<sub>2</sub>(x)) = {@code 32 - numberOfLeadingZeros(x - 1)}
* </ul>
*
* @param i the value whose number of leading zeros is to be computed
* @return the number of zero bits preceding the highest-order
* ("leftmost") one-bit in the two's complement binary representation
* of the specified {@code int} value, or 32 if the value
@ -1408,6 +1412,7 @@ public final class Integer extends Number implements Comparable<Integer> {
* one-bits in its two's complement representation, in other words if it is
* equal to zero.
*
* @param i the value whose number of trailing zeros is to be computed
* @return the number of zero bits following the lowest-order ("rightmost")
* one-bit in the two's complement binary representation of the
* specified {@code int} value, or 32 if the value is equal
@ -1431,6 +1436,7 @@ public final class Integer extends Number implements Comparable<Integer> {
* representation of the specified {@code int} value. This function is
* sometimes referred to as the <i>population count</i>.
*
* @param i the value whose bits are to be counted
* @return the number of one-bits in the two's complement binary
* representation of the specified {@code int} value.
* @since 1.5
@ -1458,6 +1464,8 @@ public final class Integer extends Number implements Comparable<Integer> {
* ignored, even if the distance is negative: {@code rotateLeft(val,
* distance) == rotateLeft(val, distance & 0x1F)}.
*
* @param i the value whose bits are to be rotated left
* @param distance the number of bit positions to rotate left
* @return the value obtained by rotating the two's complement binary
* representation of the specified {@code int} value left by the
* specified number of bits.
@ -1480,6 +1488,8 @@ public final class Integer extends Number implements Comparable<Integer> {
* ignored, even if the distance is negative: {@code rotateRight(val,
* distance) == rotateRight(val, distance & 0x1F)}.
*
* @param i the value whose bits are to be rotated right
* @param distance the number of bit positions to rotate right
* @return the value obtained by rotating the two's complement binary
* representation of the specified {@code int} value right by the
* specified number of bits.
@ -1494,6 +1504,7 @@ public final class Integer extends Number implements Comparable<Integer> {
* two's complement binary representation of the specified {@code int}
* value.
*
* @param i the value to be reversed
* @return the value obtained by reversing order of the bits in the
* specified {@code int} value.
* @since 1.5
@ -1513,6 +1524,7 @@ public final class Integer extends Number implements Comparable<Integer> {
* return value is -1 if the specified value is negative; 0 if the
* specified value is zero; and 1 if the specified value is positive.)
*
* @param i the value whose signum is to be computed
* @return the signum function of the specified {@code int} value.
* @since 1.5
*/
@ -1525,6 +1537,7 @@ public final class Integer extends Number implements Comparable<Integer> {
* Returns the value obtained by reversing the order of the bytes in the
* two's complement representation of the specified {@code int} value.
*
* @param i the value whose bytes are to be reversed
* @return the value obtained by reversing the bytes in the specified
* {@code int} value.
* @since 1.5

16
jdk/src/share/classes/java/lang/Long.java
View File

@ -1053,9 +1053,9 @@ public final class Long extends Number implements Comparable<Long> {
* Returns a hash code for a {@code long} value; compatible with
* {@code Long.hashCode()}.
*
* @since 1.8
*
* @param value the value to hash
* @return a hash code value for a {@code long} value.
* @since 1.8
*/
public static int hashCode(long value) {
return (int)(value ^ (value >>> 32));
@ -1357,6 +1357,7 @@ public final class Long extends Number implements Comparable<Long> {
* one-bits in its two's complement binary representation, that is, if it
* is equal to zero.
*
* @param i the value whose highest one bit is to be computed
* @return a {@code long} value with a single one-bit, in the position
* of the highest-order one-bit in the specified value, or zero if
* the specified value is itself equal to zero.
@ -1380,6 +1381,7 @@ public final class Long extends Number implements Comparable<Long> {
* one-bits in its two's complement binary representation, that is, if it
* is equal to zero.
*
* @param i the value whose lowest one bit is to be computed
* @return a {@code long} value with a single one-bit, in the position
* of the lowest-order one-bit in the specified value, or zero if
* the specified value is itself equal to zero.
@ -1404,6 +1406,7 @@ public final class Long extends Number implements Comparable<Long> {
* <li>ceil(log<sub>2</sub>(x)) = {@code 64 - numberOfLeadingZeros(x - 1)}
* </ul>
*
* @param i the value whose number of leading zeros is to be computed
* @return the number of zero bits preceding the highest-order
* ("leftmost") one-bit in the two's complement binary representation
* of the specified {@code long} value, or 64 if the value
@ -1432,6 +1435,7 @@ public final class Long extends Number implements Comparable<Long> {
* one-bits in its two's complement representation, in other words if it is
* equal to zero.
*
* @param i the value whose number of trailing zeros is to be computed
* @return the number of zero bits following the lowest-order ("rightmost")
* one-bit in the two's complement binary representation of the
* specified {@code long} value, or 64 if the value is equal
@ -1456,6 +1460,7 @@ public final class Long extends Number implements Comparable<Long> {
* representation of the specified {@code long} value. This function is
* sometimes referred to as the <i>population count</i>.
*
* @param i the value whose bits are to be counted
* @return the number of one-bits in the two's complement binary
* representation of the specified {@code long} value.
* @since 1.5
@ -1484,6 +1489,8 @@ public final class Long extends Number implements Comparable<Long> {
* ignored, even if the distance is negative: {@code rotateLeft(val,
* distance) == rotateLeft(val, distance & 0x3F)}.
*
* @param i the value whose bits are to be rotated left
* @param distance the number of bit positions to rotate left
* @return the value obtained by rotating the two's complement binary
* representation of the specified {@code long} value left by the
* specified number of bits.
@ -1506,6 +1513,8 @@ public final class Long extends Number implements Comparable<Long> {
* ignored, even if the distance is negative: {@code rotateRight(val,
* distance) == rotateRight(val, distance & 0x3F)}.
*
* @param i the value whose bits are to be rotated right
* @param distance the number of bit positions to rotate right
* @return the value obtained by rotating the two's complement binary
* representation of the specified {@code long} value right by the
* specified number of bits.
@ -1520,6 +1529,7 @@ public final class Long extends Number implements Comparable<Long> {
* two's complement binary representation of the specified {@code long}
* value.
*
* @param i the value to be reversed
* @return the value obtained by reversing order of the bits in the
* specified {@code long} value.
* @since 1.5
@ -1540,6 +1550,7 @@ public final class Long extends Number implements Comparable<Long> {
* return value is -1 if the specified value is negative; 0 if the
* specified value is zero; and 1 if the specified value is positive.)
*
* @param i the value whose signum is to be computed
* @return the signum function of the specified {@code long} value.
* @since 1.5
*/
@ -1552,6 +1563,7 @@ public final class Long extends Number implements Comparable<Long> {
* Returns the value obtained by reversing the order of the bytes in the
* two's complement representation of the specified {@code long} value.
*
* @param i the value whose bytes are to be reversed
* @return the value obtained by reversing the bytes in the specified
* {@code long} value.
* @since 1.5

14
jdk/src/share/classes/java/lang/Package.java
View File

@ -77,18 +77,18 @@ import java.lang.annotation.Annotation;
* by the following formal grammar:
* <blockquote>
* <dl>
* <dt><i>SpecificationVersion:
* <dd>Digits RefinedVersion<sub>opt</sub></i>
* <dt><i>SpecificationVersion:</i>
* <dd><i>Digits RefinedVersion<sub>opt</sub></i>
* <p><dt><i>RefinedVersion:</i>
* <dt><i>RefinedVersion:</i>
* <dd>{@code .} <i>Digits</i>
* <dd>{@code .} <i>Digits RefinedVersion</i>
*
* <p><dt><i>Digits:
* <dd>Digit
* <dd>Digits</i>
* <dt><i>Digits:</i>
* <dd><i>Digit</i>
* <dd><i>Digits</i>
*
* <p><dt><i>Digit:</i>
* <dt><i>Digit:</i>
* <dd>any character for which {@link Character#isDigit} returns {@code true},
* e.g. 0, 1, 2, ...
* </dl>

6
jdk/src/share/classes/java/lang/Runtime.java
View File

@ -117,11 +117,11 @@ public class Runtime {
*
* <ul>
*
* <p> <li> The program <i>exits</i> normally, when the last non-daemon
* <li> The program <i>exits</i> normally, when the last non-daemon
* thread exits or when the <tt>{@link #exit exit}</tt> (equivalently,
* <tt>{@link System#exit(int) System.exit}</tt>) method is invoked, or
* {@link System#exit(int) System.exit}) method is invoked, or
*
* <p> <li> The virtual machine is <i>terminated</i> in response to a
* <li> The virtual machine is <i>terminated</i> in response to a
* user interrupt, such as typing <tt>^C</tt>, or a system-wide event,
* such as user logoff or system shutdown.
*

7
jdk/src/share/classes/java/lang/Short.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 1996, 2012, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 1996, 2013, 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
@ -403,9 +403,9 @@ public final class Short extends Number implements Comparable<Short> {
* Returns a hash code for a {@code short} value; compatible with
* {@code Short.hashCode()}.
*
* @since 1.8
*
* @param value the value to hash
* @return a hash code value for a {@code short} value.
* @since 1.8
*/
public static int hashCode(short value) {
return (int)value;
@ -482,6 +482,7 @@ public final class Short extends Number implements Comparable<Short> {
* Returns the value obtained by reversing the order of the bytes in the
* two's complement representation of the specified {@code short} value.
*
* @param i the value whose bytes are to be reversed
* @return the value obtained by reversing (or, equivalently, swapping)
* the bytes in the specified {@code short} value.
* @since 1.5

4
jdk/src/share/classes/java/lang/StrictMath.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 1999, 2012, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 1999, 2013, 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
@ -1419,6 +1419,7 @@ public final class StrictMath {
* {@link Float#MIN_EXPONENT} -1.
* </ul>
* @param f a {@code float} value
* @return the unbiased exponent of the argument
* @since 1.6
*/
public static int getExponent(float f) {
@ -1436,6 +1437,7 @@ public final class StrictMath {
* {@link Double#MIN_EXPONENT} -1.
* </ul>
* @param d a {@code double} value
* @return the unbiased exponent of the argument
* @since 1.6
*/
public static int getExponent(double d) {

1
jdk/src/share/classes/java/lang/SuppressWarnings.java
View File

@ -66,6 +66,7 @@ public @interface SuppressWarnings {
* additional warning names they support in conjunction with this
* annotation type. They are encouraged to cooperate to ensure
* that the same names work across multiple compilers.
* @return the set of warnings to be suppressed
*/
String[] value();
}

2
jdk/src/share/classes/java/lang/System.java
View File

@ -634,6 +634,8 @@ public final class System {
*
* <p>On UNIX systems, it returns {@code "\n"}; on Microsoft
* Windows systems it returns {@code "\r\n"}.
*
* @return the system-dependent line separator string
* @since 1.7
*/
public static String lineSeparator() {

3
jdk/src/share/classes/java/lang/annotation/Annotation.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2003, 2011, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2003, 2013, 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
@ -126,6 +126,7 @@ public interface Annotation {
/**
* Returns the annotation type of this annotation.
* @return the annotation type of this annotation
*/
Class<? extends Annotation> annotationType();
}

3
jdk/src/share/classes/java/lang/annotation/Repeatable.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2012, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2012, 2013, 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,6 +43,7 @@ public @interface Repeatable {
/**
* Indicates the <em>containing annotation type</em> for the
* repeatable annotation type.
* @return the containing annotation type
*/
Class<? extends Annotation> value();
}

4
jdk/src/share/classes/java/lang/annotation/Retention.java
View File

@ -44,5 +44,9 @@ package java.lang.annotation;
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.ANNOTATION_TYPE)
public @interface Retention {
/**
* Returns the retention policy.
* @return the retention policy
*/
RetentionPolicy value();
}

6
jdk/src/share/classes/java/lang/annotation/Target.java
View File

@ -67,5 +67,11 @@ package java.lang.annotation;
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.ANNOTATION_TYPE)
public @interface Target {
/**
* Returns an array of the kinds of elements an annotation type
* can be applied to.
* @return an array of the kinds of elements an annotation type
* can be applied to
*/
ElementType[] value();
}

5
jdk/src/share/classes/java/lang/reflect/AnnotatedElement.java
View File

@ -130,6 +130,7 @@ public interface AnnotatedElement {
* Returns this element's annotation for the specified type if
* such an annotation is present, else null.
*
* @param <T> the type of the annotation to query for and return if present
* @param annotationClass the Class object corresponding to the
* annotation type
* @return this element's annotation for the specified annotation type if
@ -154,6 +155,7 @@ public interface AnnotatedElement {
* The caller of this method is free to modify the returned array; it will
* have no effect on the arrays returned to other callers.
*
* @param <T> the type of the annotation to query for and return if present
* @param annotationClass the Class object corresponding to the
* annotation type
* @return all this element's annotations for the specified annotation type if
@ -184,6 +186,7 @@ public interface AnnotatedElement {
* This method ignores inherited annotations. (Returns null if no
* annotations are directly present on this element.)
*
* @param <T> the type of the annotation to query for and return if present
* @param annotationClass the Class object corresponding to the
* annotation type
* @return this element's annotation for the specified annotation type if
@ -209,6 +212,8 @@ public interface AnnotatedElement {
* The caller of this method is free to modify the returned array; it will
* have no effect on the arrays returned to other callers.
*
* @param <T> the type of the annotation to query for and return
* if directly present
* @param annotationClass the Class object corresponding to the
* annotation type
* @return all this element's annotations for the specified annotation type if

13
jdk/src/share/classes/java/lang/reflect/Executable.java
View File

@ -384,6 +384,8 @@ public abstract class Executable extends AccessibleObject
/**
* Returns a string describing this {@code Executable}, including
* any type parameters.
* @return a string describing this {@code Executable}, including
* any type parameters
*/
public abstract String toGenericString();
@ -496,6 +498,8 @@ public abstract class Executable extends AccessibleObject
* If this Executable represents a method, the AnnotatedType object
* represents the use of a type to specify the return type of the method.
*
* @return an object representing the return type of this method
* or constructor
* @since 1.8
*/
public abstract AnnotatedType getAnnotatedReturnType();
@ -531,6 +535,9 @@ public abstract class Executable extends AccessibleObject
*
* Returns null if this Executable represents a static method.
*
* @return an object representing the receiver type of the
* method or constructor represented by this Executable
*
* @since 1.8
*/
public AnnotatedType getAnnotatedReceiverType() {
@ -553,6 +560,9 @@ public abstract class Executable extends AccessibleObject
* Returns an array of length 0 if the method/constructor declares no
* parameters.
*
* @return an array of objects representing the types of the
* formal parameters of this method or constructor
*
* @since 1.8
*/
public AnnotatedType[] getAnnotatedParameterTypes() {
@ -575,6 +585,9 @@ public abstract class Executable extends AccessibleObject
* Returns an array of length 0 if the method/constructor declares no
* exceptions.
*
* @return an array of objects representing the declared
* exceptions of this method or constructor
*
* @since 1.8
*/
public AnnotatedType[] getAnnotatedExceptionTypes() {

2
jdk/src/share/classes/java/lang/reflect/Field.java
View File

@ -1151,6 +1151,8 @@ class Field extends AccessibleObject implements Member {
/**
* Returns an AnnotatedType object that represents the use of a type to specify
* the declared type of the field represented by this Field.
* @return an object representing the declared type of the field
* represented by this Field
*
* @since 1.8
*/

2
jdk/src/share/classes/java/lang/reflect/Parameter.java
View File

@ -152,6 +152,8 @@ public final class Parameter implements AnnotatedElement {
* defined in a class file, then that name will be returned by
* this method. Otherwise, this method will synthesize a name of
* the form argN, where N is the index of the parameter.
*
* @return the name of the parameter
*/
public String getName() {
// Note: empty strings as paramete names are now outlawed.

1
jdk/src/share/classes/java/lang/reflect/TypeVariable.java
View File

@ -95,6 +95,7 @@ public interface TypeVariable<D extends GenericDeclaration> extends Type, Annota
*
* Returns an array of length 0 if the type parameter declares no bounds.
*
* @return an array of objects representing the upper bounds of the type variable
* @since 1.8
*/
AnnotatedType[] getAnnotatedBounds();