infernap12/jdk
1
0
Fork 0
mirror of https://github.com/openjdk/jdk.git synced 2026-05-11 05:59:52 +00:00
Code Issues Packages Projects Releases Wiki Activity

8256917: Use combo @returns tag in java.compiler javadoc

Browse Source 
Reviewed-by: jjg, iris
This commit is contained in:
Joe Darcy 2020-12-09 02:37:30 +00:00
parent b29f9cd7b0
commit 2a62d5d34f
33 changed files with 161 additions and 329 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
src/java.compiler/share/classes/javax/annotation/processing/AbstractProcessor.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2005, 2019, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2005, 2020, 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
@ -171,7 +171,7 @@ public abstract class AbstractProcessor implements Processor {
RoundEnvironment roundEnv);
/**
* Returns an empty iterable of completions.
* {@return an empty iterable of completions}
*
* @param element {@inheritDoc}
* @param annotation {@inheritDoc}
@ -186,11 +186,8 @@ public abstract class AbstractProcessor implements Processor {
}
/**
* Returns {@code true} if this object has been {@linkplain #init
* initialized}, {@code false} otherwise.
*
* @return {@code true} if this object has been initialized,
* {@code false} otherwise.
* {@return {@code true} if this object has been {@linkplain #init
* initialized}, {@code false} otherwise}
*/
protected synchronized boolean isInitialized() {
return initialized;

8
src/java.compiler/share/classes/javax/annotation/processing/Completion.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2006, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2006, 2020, 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
@ -38,14 +38,12 @@ package javax.annotation.processing;
public interface Completion {
/**
* Returns the text of the suggested completion.
* @return the text of the suggested completion.
* {@return the text of the suggested completion}
*/
String getValue();
/**
* Returns an informative message about the completion.
* @return an informative message about the completion.
* {@return an informative message about the completion}
*/
String getMessage();
}

8
src/java.compiler/share/classes/javax/annotation/processing/Completions.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2006, 2012, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2006, 2020, 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
@ -65,21 +65,19 @@ public class Completions {
}
/**
* Returns a completion of the value and message.
* {@return a completion of the value and message}
*
* @param value the text of the completion
* @param message a message about the completion
* @return a completion of the provided value and message
*/
public static Completion of(String value, String message) {
return new SimpleCompletion(value, message);
}
/**
* Returns a completion of the value and an empty message
* {@return a completion of the value and an empty message}
*
* @param value the text of the completion
* @return a completion of the value and an empty message
*/
public static Completion of(String value) {
return new SimpleCompletion(value, "");

45
src/java.compiler/share/classes/javax/annotation/processing/ProcessingEnvironment.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2005, 2019, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2005, 2020, 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
@ -60,8 +60,8 @@ import javax.lang.model.util.Types;
*/
public interface ProcessingEnvironment {
/**
* Returns the processor-specific options passed to the annotation
* processing tool. Options are returned in the form of a map from
* {@return the processor-specific options passed to the annotation
* processing tool} Options are returned in the form of a map from
* option name to option value. For an option with no value, the
* corresponding value in the map is {@code null}.
*
@ -74,61 +74,46 @@ public interface ProcessingEnvironment {
* A given implementation may also provide implementation-specific
* ways of finding options passed to the tool in addition to the
* processor-specific options.
*
* @return the processor-specific options passed to the tool
*/
Map<String,String> getOptions();
/**
* Returns the messager used to report errors, warnings, and other
* notices.
*
* @return the messager
* {@return the messager used to report errors, warnings, and other
* notices}
*/
Messager getMessager();
/**
* Returns the filer used to create new source, class, or auxiliary
* files.
*
* @return the filer
* {@return the filer used to create new source, class, or auxiliary
* files}
*/
Filer getFiler();
/**
* Returns an implementation of some utility methods for
* operating on elements
*
* @return element utilities
* {@return an implementation of some utility methods for
* operating on elements}
*/
Elements getElementUtils();
/**
* Returns an implementation of some utility methods for
* operating on types.
*
* @return type utilities
* {@return an implementation of some utility methods for
* operating on types}
*/
Types getTypeUtils();
/**
* Returns the source version that any generated {@linkplain
* {@return the source version that any generated {@linkplain
* Filer#createSourceFile source} and {@linkplain
* Filer#createClassFile class} files should conform to.
* Filer#createClassFile class} files should conform to}
*
* @return the source version to which generated source and class
* files should conform to
* @see Processor#getSupportedSourceVersion
*/
SourceVersion getSourceVersion();
/**
* Returns the current locale or {@code null} if no locale is in
* effect. The locale can be be used to provide localized
* {@return the current locale or {@code null} if no locale is in
* effect} The locale can be be used to provide localized
* {@linkplain Messager messages}.
*
* @return the current locale or {@code null} if no locale is in
* effect
*/
Locale getLocale();

6
src/java.compiler/share/classes/javax/annotation/processing/Processor.java
View File

@ -305,11 +305,9 @@ public interface Processor {
Set<String> getSupportedAnnotationTypes();
/**
* Returns the latest source version supported by this annotation
* processor.
* {@return the latest source version supported by this annotation
* processor}
*
* @return the latest source version supported by this annotation
* processor.
* @see javax.annotation.processing.SupportedSourceVersion
* @see ProcessingEnvironment#getSourceVersion
*/

17
src/java.compiler/share/classes/javax/annotation/processing/RoundEnvironment.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2005, 2019, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2005, 2020, 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
@ -45,22 +45,15 @@ import java.lang.annotation.Annotation;
*/
public interface RoundEnvironment {
/**
* Returns {@code true} if types generated by this round will not
* {@return {@code true} if types generated by this round will not
* be subject to a subsequent round of annotation processing;
* returns {@code false} otherwise.
*
* @return {@code true} if types generated by this round will not
* be subject to a subsequent round of annotation processing;
* returns {@code false} otherwise
* returns {@code false} otherwise}
*/
boolean processingOver();
/**
* Returns {@code true} if an error was raised in the prior round
* of processing; returns {@code false} otherwise.
*
* @return {@code true} if an error was raised in the prior round
* of processing; returns {@code false} otherwise
* {@return {@code true} if an error was raised in the prior round
* of processing; returns {@code false} otherwise}
*/
boolean errorRaised();

5
src/java.compiler/share/classes/javax/annotation/processing/SupportedAnnotationTypes.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2005, 2020, 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
@ -48,8 +48,7 @@ import static java.lang.annotation.ElementType.*;
@Retention(RUNTIME)
public @interface SupportedAnnotationTypes {
/**
* Returns the names of the supported annotation types.
* @return the names of the supported annotation types
* {@return the names of the supported annotation types}
*/
String [] value();
}

5
src/java.compiler/share/classes/javax/annotation/processing/SupportedOptions.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2005, 2020, 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
@ -47,8 +47,7 @@ import static java.lang.annotation.ElementType.*;
@Retention(RUNTIME)
public @interface SupportedOptions {
/**
* Returns the supported options.
* @return the supported options
* {@return the supported options}
*/
String [] value();
}

5
src/java.compiler/share/classes/javax/annotation/processing/SupportedSourceVersion.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2005, 2020, 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
@ -48,8 +48,7 @@ import javax.lang.model.SourceVersion;
@Retention(RUNTIME)
public @interface SupportedSourceVersion {
/**
* Returns the latest supported source version.
* @return the latest supported source version
* {@return the latest supported source version}
*/
SourceVersion value();
}

6
src/java.compiler/share/classes/javax/lang/model/AnnotatedConstruct.java
View File

@ -145,8 +145,8 @@ public interface AnnotatedConstruct {
List<? extends AnnotationMirror> getAnnotationMirrors();
/**
* Returns this construct's annotation of the specified type if
* such an annotation is <em>present</em>, else {@code null}.
* {@return this construct's annotation of the specified type if
* such an annotation is <em>present</em>, else {@code null}}
*
* <p> The annotation returned by this method could contain an element
* whose value is of type {@code Class}.
@ -176,8 +176,6 @@ public interface AnnotatedConstruct {
* @param <A> the annotation type
* @param annotationType the {@code Class} object corresponding to
* the annotation type
* @return this construct's annotation for the specified
* annotation type if present, else {@code null}
*
* @see #getAnnotationMirrors()
* @see java.lang.reflect.AnnotatedElement#getAnnotation

10
src/java.compiler/share/classes/javax/lang/model/SourceVersion.java
View File

@ -229,9 +229,7 @@ public enum SourceVersion {
// behavior of latest() and latestSupported() must be updated too.
/**
* Returns the latest source version that can be modeled.
*
* @return the latest source version that can be modeled
* {@return the latest source version that can be modeled}
*/
public static SourceVersion latest() {
return RELEASE_16;
@ -254,8 +252,8 @@ public enum SourceVersion {
}
/**
* Returns the latest source version fully supported by the
* current execution environment. {@code RELEASE_9} or later must
* {@return the latest source version fully supported by the
* current execution environment} {@code RELEASE_9} or later must
* be returned.
*
* @apiNote This method is included alongside {@link latest} to
@ -272,8 +270,6 @@ public enum SourceVersion {
* current execution environment, the processor should only use
* platform features up to the {@code latestSupported} release,
* which may be earlier than the {@code latest} release.
*
* @return the latest source version that is fully supported
*/
public static SourceVersion latestSupported() {
return latestSupported;

6
src/java.compiler/share/classes/javax/lang/model/element/AnnotationMirror.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2005, 2006, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2005, 2020, 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
@ -44,9 +44,7 @@ import javax.lang.model.type.DeclaredType;
public interface AnnotationMirror {
/**
* Returns the type of this annotation.
*
* @return the type of this annotation
* {@return the type of this annotation}
*/
DeclaredType getAnnotationType();

10
src/java.compiler/share/classes/javax/lang/model/element/AnnotationValue.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2005, 2012, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2005, 2020, 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
@ -45,18 +45,14 @@ package javax.lang.model.element;
public interface AnnotationValue {
/**
* Returns the value.
*
* @return the value
* {@return the value}
*/
Object getValue();
/**
* Returns a string representation of this value.
* {@return a string representation of this value}
* This is returned in a form suitable for representing this value
* in the source code of an annotation.
*
* @return a string representation of this value
*/
String toString();

16
src/java.compiler/share/classes/javax/lang/model/element/Element.java
View File

@ -61,8 +61,7 @@ import javax.lang.model.util.*;
*/
public interface Element extends javax.lang.model.AnnotatedConstruct {
/**
* Returns the type defined by this element.
* @return the type defined by this element
* {@return the type defined by this element}
*
* @see Types
* @see ExecutableElement#asType
@ -75,7 +74,7 @@ public interface Element extends javax.lang.model.AnnotatedConstruct {
TypeMirror asType();
/**
* Returns the {@code kind} of this element.
* {@return the {@code kind} of this element}
*
* <ul>
*
@ -113,8 +112,6 @@ public interface Element extends javax.lang.model.AnnotatedConstruct {
* RECORD_COMPONENT}.
*
* </ul>
*
* @return the kind of this element
*/
ElementKind getKind();
@ -128,7 +125,7 @@ public interface Element extends javax.lang.model.AnnotatedConstruct {
Set<Modifier> getModifiers();
/**
* Returns the simple (unqualified) name of this element. The
* {@return the simple (unqualified) name of this element} The
* name of a generic type does not include any reference to its
* formal type parameters.
*
@ -150,7 +147,6 @@ public interface Element extends javax.lang.model.AnnotatedConstruct {
* instance initializer}, an <a href=Name.html#empty_name>empty
* name</a> is returned.
*
* @return the simple name of this element
* @see PackageElement#getSimpleName
* @see ExecutableElement#getSimpleName
* @see TypeElement#getSimpleName
@ -239,8 +235,8 @@ public interface Element extends javax.lang.model.AnnotatedConstruct {
List<? extends Element> getEnclosedElements();
/**
* Returns {@code true} if the argument represents the same
* element as {@code this}, or {@code false} otherwise.
* {@return {@code true} if the argument represents the same
* element as {@code this}, or {@code false} otherwise}
*
* @apiNote The identity of an element involves implicit state
* not directly accessible from the element's methods, including
@ -252,8 +248,6 @@ public interface Element extends javax.lang.model.AnnotatedConstruct {
* different class loaders.
*
* @param obj the object to be compared with this element
* @return {@code true} if the specified object represents the same
* element as this
*/
@Override
boolean equals(Object obj);

31
src/java.compiler/share/classes/javax/lang/model/element/ExecutableElement.java
View File

@ -41,10 +41,8 @@ import javax.lang.model.type.*;
*/
public interface ExecutableElement extends Element, Parameterizable {
/**
* Returns the {@linkplain ExecutableType executable type} defined
* by this executable element.
*
* @return the executable type defined by this executable element
* {@return the {@linkplain ExecutableType executable type} defined
* by this executable element}
*
* @see ExecutableType
*/
@ -61,12 +59,10 @@ public interface ExecutableElement extends Element, Parameterizable {
List<? extends TypeParameterElement> getTypeParameters();
/**
* Returns the return type of this executable.
* {@return the return type of this executable}
* Returns a {@link NoType} with kind {@link TypeKind#VOID VOID}
* if this executable is not a method, or is a method that does not
* return a value.
*
* @return the return type of this executable
*/
TypeMirror getReturnType();
@ -103,20 +99,14 @@ public interface ExecutableElement extends Element, Parameterizable {
TypeMirror getReceiverType();
/**
* Returns {@code true} if this method or constructor accepts a variable
* number of arguments and returns {@code false} otherwise.
*
* @return {@code true} if this method or constructor accepts a variable
* number of arguments and {@code false} otherwise
* {@return {@code true} if this method or constructor accepts a variable
* number of arguments and returns {@code false} otherwise}
*/
boolean isVarArgs();
/**
* Returns {@code true} if this method is a default method and
* returns {@code false} otherwise.
*
* @return {@code true} if this method is a default method and
* {@code false} otherwise
* {@return {@code true} if this method is a default method and
* returns {@code false} otherwise}
* @since 1.8
*/
boolean isDefault();
@ -142,15 +132,12 @@ public interface ExecutableElement extends Element, Parameterizable {
AnnotationValue getDefaultValue();
/**
* Returns the simple name of a constructor, method, or
* initializer. For a constructor, the name {@code "<init>"} is
* {@return the simple name of a constructor, method, or
* initializer} For a constructor, the name {@code "<init>"} is
* returned, for a static initializer, the name {@code "<clinit>"}
* is returned, and for an anonymous class or instance
* initializer, an <a href=Name.html#empty_name>empty name</a> is
* returned.
*
* @return the simple name of a constructor, method, or
* initializer
*/
@Override
Name getSimpleName();

50
src/java.compiler/share/classes/javax/lang/model/element/ModuleElement.java
View File

@ -38,9 +38,8 @@ import javax.lang.model.type.TypeMirror;
*/
public interface ModuleElement extends Element, QualifiedNameable {
/**
* Returns a {@linkplain javax.lang.model.type.NoType pseudo-type}
* for this module.
* @return a pseudo-type for this module
* {@return a {@linkplain javax.lang.model.type.NoType pseudo-type}
* for this module}
*
* @see javax.lang.model.type.NoType
* @see javax.lang.model.type.TypeKind#MODULE
@ -87,27 +86,20 @@ public interface ModuleElement extends Element, QualifiedNameable {
Name getSimpleName();
/**
* Returns the packages within this module.
* @return the packages within this module
* {@return the packages within this module}
*/
@Override
List<? extends Element> getEnclosedElements();
/**
* Returns {@code true} if this is an open module and {@code
* false} otherwise.
*
* @return {@code true} if this is an open module and {@code
* false} otherwise
* {@return {@code true} if this is an open module and {@code
* false} otherwise}
*/
boolean isOpen();
/**
* Returns {@code true} if this is an unnamed module and {@code
* false} otherwise.
*
* @return {@code true} if this is an unnamed module and {@code
* false} otherwise
* {@return {@code true} if this is an unnamed module and {@code
* false} otherwise}
*
* @jls 7.7.5 Unnamed Modules
*/
@ -159,7 +151,7 @@ public interface ModuleElement extends Element, QualifiedNameable {
*/
interface Directive {
/**
* Returns the {@code kind} of this directive.
* {@return the {@code kind} of this directive}
* <ul>
*
* <li> The kind of a {@linkplain RequiresDirective requires
@ -178,8 +170,6 @@ public interface ModuleElement extends Element, QualifiedNameable {
* directive} is {@link DirectiveKind#PROVIDES PROVIDES}.
*
* </ul>
*
* @return the kind of this directive
*/
DirectiveKind getKind();
@ -310,20 +300,17 @@ public interface ModuleElement extends Element, QualifiedNameable {
*/
interface RequiresDirective extends Directive {
/**
* Returns whether or not this is a static dependency.
* @return whether or not this is a static dependency
* {@return whether or not this is a static dependency}
*/
boolean isStatic();
/**
* Returns whether or not this is a transitive dependency.
* @return whether or not this is a transitive dependency
* {@return whether or not this is a transitive dependency}
*/
boolean isTransitive();
/**
* Returns the module that is required
* @return the module that is required
* {@return the module that is required}
*/
ModuleElement getDependency();
}
@ -335,8 +322,7 @@ public interface ModuleElement extends Element, QualifiedNameable {
interface ExportsDirective extends Directive {
/**
* Returns the package being exported.
* @return the package being exported
* {@return the package being exported}
*/
PackageElement getPackage();
@ -356,8 +342,7 @@ public interface ModuleElement extends Element, QualifiedNameable {
interface OpensDirective extends Directive {
/**
* Returns the package being opened.
* @return the package being opened
* {@return the package being opened}
*/
PackageElement getPackage();
@ -376,14 +361,12 @@ public interface ModuleElement extends Element, QualifiedNameable {
*/
interface ProvidesDirective extends Directive {
/**
* Returns the service being provided.
* @return the service being provided
* {@return the service being provided}
*/
TypeElement getService();
/**
* Returns the implementations of the service being provided.
* @return the implementations of the service being provided
* {@return the implementations of the service being provided}
*/
List<? extends TypeElement> getImplementations();
}
@ -394,8 +377,7 @@ public interface ModuleElement extends Element, QualifiedNameable {
*/
interface UsesDirective extends Directive {
/**
* Returns the service that is used.
* @return the service that is used
* {@return the service that is used}
*/
TypeElement getService();
}

24
src/java.compiler/share/classes/javax/lang/model/element/PackageElement.java
View File

@ -40,9 +40,8 @@ import javax.lang.model.type.TypeMirror;
*/
public interface PackageElement extends Element, QualifiedNameable {
/**
* Returns a {@linkplain javax.lang.model.type.NoType pseudo-type}
* for this package.
* @return a pseudo-type for this package
* {@return a {@linkplain javax.lang.model.type.NoType pseudo-type}
* for this package}
*
* @see javax.lang.model.type.NoType
* @see javax.lang.model.type.TypeKind#PACKAGE
@ -81,30 +80,25 @@ public interface PackageElement extends Element, QualifiedNameable {
Name getSimpleName();
/**
* Returns the {@linkplain NestingKind#TOP_LEVEL top-level}
* classes and interfaces within this package. Note that
* {@return the {@linkplain NestingKind#TOP_LEVEL top-level}
* classes and interfaces within this package} Note that
* subpackages are <em>not</em> considered to be enclosed by a
* package.
*
* @return the top-level classes and interfaces within this
* package
*/
@Override
List<? extends Element> getEnclosedElements();
/**
* Returns {@code true} if this is an unnamed package and {@code
* false} otherwise.
* {@return {@code true} if this is an unnamed package and {@code
* false} otherwise}
*
* @return {@code true} if this is an unnamed package and {@code
* false} otherwise
* @jls 7.4.2 Unnamed Packages
*/
boolean isUnnamed();
/**
* Returns the enclosing module if such a module exists; otherwise
* returns {@code null}.
* {@return the enclosing module if such a module exists; otherwise
* {@code null}}
*
* One situation where a module does not exist for a package is if
* the environment does not include modules, such as an annotation
@ -112,8 +106,6 @@ public interface PackageElement extends Element, QualifiedNameable {
* javax.annotation.processing.ProcessingEnvironment#getSourceVersion
* source version} without modules.
*
* @return the enclosing module or {@code null} if no such module exists
*
* @revised 9
*/
@Override

6
src/java.compiler/share/classes/javax/lang/model/element/QualifiedNameable.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2009, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2009, 2020, 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
@ -33,9 +33,7 @@ package javax.lang.model.element;
*/
public interface QualifiedNameable extends Element {
/**
* Returns the fully qualified name of an element.
*
* @return the fully qualified name of an element
* {@return the fully qualified name of an element}
*/
Name getQualifiedName();
}

8
src/java.compiler/share/classes/javax/lang/model/element/RecordComponentElement.java
View File

@ -32,24 +32,20 @@ package javax.lang.model.element;
*/
public interface RecordComponentElement extends Element {
/**
* Returns the enclosing element of this record component.
* {@return the enclosing element of this record component}
*
* The enclosing element of a record component is the type
* declaring the record component.
*
* @return the enclosing element of this record component
*/
@Override
Element getEnclosingElement();
/**
* Returns the simple name of this record component.
* {@return the simple name of this record component}
*
* <p>The name of each record component must be distinct from the
* names of all other record components of the same record.
*
* @return the simple name of this record component
*
* @jls 6.2 Names and Identifiers
*/
@Override

19
src/java.compiler/share/classes/javax/lang/model/element/TypeParameterElement.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2005, 2019, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2005, 2020, 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
@ -42,21 +42,17 @@ import javax.lang.model.type.TypeVariable;
*/
public interface TypeParameterElement extends Element {
/**
* Returns the {@linkplain TypeVariable type variable} corresponding to this type parameter element.
* {@return the {@linkplain TypeVariable type variable}
* corresponding to this type parameter element}
*
* @see TypeVariable
*
* @return the type variable corresponding to this type parameter element
*/
@Override
TypeMirror asType();
/**
* Returns the generic class, interface, method, or constructor that is
* parameterized by this type parameter.
*
* @return the generic class, interface, method, or constructor that is
* parameterized by this type parameter
* {@return the generic class, interface, method, or constructor that is
* parameterized by this type parameter}
*/
Element getGenericElement();
@ -73,9 +69,8 @@ public interface TypeParameterElement extends Element {
List<? extends TypeMirror> getBounds();
/**
* Returns the {@linkplain TypeParameterElement#getGenericElement generic element} of this type parameter.
*
* @return the generic element of this type parameter
* {@return the {@linkplain TypeParameterElement#getGenericElement
* generic element} of this type parameter}
*/
@Override
Element getEnclosingElement();

12
src/java.compiler/share/classes/javax/lang/model/element/VariableElement.java
View File

@ -41,14 +41,12 @@ import javax.lang.model.type.TypeKind;
*/
public interface VariableElement extends Element {
/**
* Returns the type of this variable.
* {@return the type of this variable}
*
* Note that the types of variables range over {@linkplain
* TypeKind many kinds} of types, including primitive types,
* declared types, and array types, among others.
*
* @return the type of this variable
*
* @see TypeKind
*/
@Override
@ -79,26 +77,22 @@ public interface VariableElement extends Element {
Object getConstantValue();
/**
* Returns the simple name of this variable element.
* {@return the simple name of this variable element}
*
* <p>For method and constructor parameters, the name of each
* parameter must be distinct from the names of all other
* parameters of the same executable. If the original source
* names are not available, an implementation may synthesize names
* subject to the distinctness requirement above.
*
* @return the simple name of this variable element
*/
@Override
Name getSimpleName();
/**
* Returns the enclosing element of this variable.
* {@return the enclosing element of this variable}
*
* The enclosing element of a method or constructor parameter is
* the executable declaring the parameter.
*
* @return the enclosing element of this variable
*/
@Override
Element getEnclosingElement();

6
src/java.compiler/share/classes/javax/lang/model/type/ArrayType.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2005, 2006, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2005, 2020, 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,9 +39,7 @@ package javax.lang.model.type;
public interface ArrayType extends ReferenceType {
/**
* Returns the component type of this array type.
*
* @return the component type of this array type
* {@return the component type of this array type}
*/
TypeMirror getComponentType();
}

6
src/java.compiler/share/classes/javax/lang/model/type/DeclaredType.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2005, 2020, 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
@ -58,9 +58,7 @@ import javax.lang.model.util.Types;
public interface DeclaredType extends ReferenceType {
/**
* Returns the element corresponding to this type.
*
* @return the element corresponding to this type
* {@return the element corresponding to this type}
*/
Element asElement();

6
src/java.compiler/share/classes/javax/lang/model/type/ExecutableType.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2005, 2020, 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
@ -59,12 +59,10 @@ public interface ExecutableType extends TypeMirror {
List<? extends TypeVariable> getTypeVariables();
/**
* Returns the return type of this executable.
* {@return the return type of this executable}
* Returns a {@link NoType} with kind {@link TypeKind#VOID VOID}
* if this executable is not a method, or is a method that does not
* return a value.
*
* @return the return type of this executable
*/
TypeMirror getReturnType();

6
src/java.compiler/share/classes/javax/lang/model/type/IntersectionType.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2012, 2017, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2012, 2020, 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
@ -45,9 +45,7 @@ import java.util.List;
public interface IntersectionType extends TypeMirror {
/**
* Return the bounds comprising this intersection type.
*
* @return the bounds of this intersection type
* {@return the bounds comprising this intersection type}
*/
List<? extends TypeMirror> getBounds();
}

7
src/java.compiler/share/classes/javax/lang/model/type/TypeKind.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2005, 2016, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2005, 2020, 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
@ -161,9 +161,8 @@ public enum TypeKind {
MODULE;
/**
* Returns {@code true} if this kind corresponds to a primitive
* type and {@code false} otherwise.
* @return {@code true} if this kind corresponds to a primitive type
* {@return {@code true} if this kind corresponds to a primitive
* type and {@code false} otherwise}
*/
public boolean isPrimitive() {
switch(this) {

4
src/java.compiler/share/classes/javax/lang/model/type/TypeMirror.java
View File

@ -68,7 +68,7 @@ import javax.lang.model.util.Types;
public interface TypeMirror extends javax.lang.model.AnnotatedConstruct {
/**
* Returns the {@code kind} of this type.
* {@return the {@code kind} of this type}
*
* <ul>
*
@ -109,8 +109,6 @@ public interface TypeMirror extends javax.lang.model.AnnotatedConstruct {
* type} is {@link TypeKind#INTERSECTION INTERSECTION}.
*
* </ul>
*
* @return the kind of this type
*/
TypeKind getKind();

10
src/java.compiler/share/classes/javax/lang/model/type/TypeVariable.java
View File

@ -51,14 +51,12 @@ import javax.lang.model.util.Types;
public interface TypeVariable extends ReferenceType {
/**
* Returns the element corresponding to this type variable.
*
* @return the element corresponding to this type variable
* {@return the element corresponding to this type variable}
*/
Element asElement();
/**
* Returns the upper bound of this type variable.
* {@return the upper bound of this type variable}
*
* <p> If this type variable was declared with no explicit
* upper bounds, the result is {@code java.lang.Object}.
@ -67,19 +65,17 @@ public interface TypeVariable extends ReferenceType {
* individual bounds can be found by examining the result's
* {@linkplain IntersectionType#getBounds() bounds}.
*
* @return the upper bound of this type variable
* @jls 4.9 Intersection Types
*/
TypeMirror getUpperBound();
/**
* Returns the lower bound of this type variable. While a type
* {@return the lower bound of this type variable} While a type
* parameter cannot include an explicit lower bound declaration,
* capture conversion can produce a type variable with a
* non-trivial lower bound. Type variables otherwise have a
* lower bound of {@link NullType}.
*
* @return the lower bound of this type variable
* @jls 18.1.3. Bounds
*/
TypeMirror getLowerBound();

4
src/java.compiler/share/classes/javax/lang/model/type/UnionType.java
View File

@ -39,9 +39,7 @@ import java.util.List;
public interface UnionType extends TypeMirror {
/**
* Return the alternatives comprising this union type.
*
* @return the alternatives comprising this union type.
* {@return the alternatives comprising this union type}
*/
List<? extends TypeMirror> getAlternatives();
}

8
src/java.compiler/share/classes/javax/lang/model/type/WildcardType.java
View File

@ -47,20 +47,16 @@ package javax.lang.model.type;
public interface WildcardType extends TypeMirror {
/**
* Returns the upper bound of this wildcard.
* {@return the upper bound of this wildcard}
* If no upper bound is explicitly declared,
* {@code null} is returned.
*
* @return the upper bound of this wildcard
*/
TypeMirror getExtendsBound();
/**
* Returns the lower bound of this wildcard.
* {@return the lower bound of this wildcard}
* If no lower bound is explicitly declared,
* {@code null} is returned.
*
* @return the lower bound of this wildcard
*/
TypeMirror getSuperBound();
}

59
src/java.compiler/share/classes/javax/lang/model/util/ElementFilter.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2005, 2019, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2005, 2020, 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
@ -92,8 +92,7 @@ public class ElementFilter {
Set.of(ElementKind.RECORD_COMPONENT);
/**
* Returns a list of fields in {@code elements}.
* @return a list of fields in {@code elements}
* {@return a list of fields in {@code elements}}
* @param elements the elements to filter
*/
public static List<VariableElement>
@ -102,8 +101,7 @@ public class ElementFilter {
}
/**
* Returns a set of fields in {@code elements}.
* @return a set of fields in {@code elements}
* {@return a set of fields in {@code elements}}
* @param elements the elements to filter
*/
public static Set<VariableElement>
@ -112,8 +110,7 @@ public class ElementFilter {
}
/**
* Returns a list of record components in {@code elements}.
* @return a list of record components in {@code elements}
* {@return a list of record components in {@code elements}}
* @param elements the elements to filter
* @since 16
*/
@ -123,8 +120,7 @@ public class ElementFilter {
}
/**
* Returns a set of record components in {@code elements}.
* @return a set of record components in {@code elements}
* {@return a set of record components in {@code elements}}
* @param elements the elements to filter
* @since 16
*/
@ -134,8 +130,7 @@ public class ElementFilter {
}
/**
* Returns a list of constructors in {@code elements}.
* @return a list of constructors in {@code elements}
* {@return a list of constructors in {@code elements}}
* @param elements the elements to filter
*/
public static List<ExecutableElement>
@ -144,8 +139,7 @@ public class ElementFilter {
}
/**
* Returns a set of constructors in {@code elements}.
* @return a set of constructors in {@code elements}
* {@return a set of constructors in {@code elements}}
* @param elements the elements to filter
*/
public static Set<ExecutableElement>
@ -154,8 +148,7 @@ public class ElementFilter {
}
/**
* Returns a list of methods in {@code elements}.
* @return a list of methods in {@code elements}
* {@return a list of methods in {@code elements}}
* @param elements the elements to filter
*/
public static List<ExecutableElement>
@ -164,8 +157,7 @@ public class ElementFilter {
}
/**
* Returns a set of methods in {@code elements}.
* @return a set of methods in {@code elements}
* {@return a set of methods in {@code elements}}
* @param elements the elements to filter
*/
public static Set<ExecutableElement>
@ -174,8 +166,7 @@ public class ElementFilter {
}
/**
* Returns a list of types in {@code elements}.
* @return a list of types in {@code elements}
* {@return a list of types in {@code elements}}
* @param elements the elements to filter
*/
public static List<TypeElement>
@ -184,8 +175,7 @@ public class ElementFilter {
}
/**
* Returns a set of types in {@code elements}.
* @return a set of types in {@code elements}
* {@return a set of types in {@code elements}}
* @param elements the elements to filter
*/
public static Set<TypeElement>
@ -194,8 +184,7 @@ public class ElementFilter {
}
/**
* Returns a list of packages in {@code elements}.
* @return a list of packages in {@code elements}
* {@return a list of packages in {@code elements}}
* @param elements the elements to filter
*/
public static List<PackageElement>
@ -204,8 +193,7 @@ public class ElementFilter {
}
/**
* Returns a set of packages in {@code elements}.
* @return a set of packages in {@code elements}
* {@return a set of packages in {@code elements}}
* @param elements the elements to filter
*/
public static Set<PackageElement>
@ -214,8 +202,7 @@ public class ElementFilter {
}
/**
* Returns a list of modules in {@code elements}.
* @return a list of modules in {@code elements}
* {@return a list of modules in {@code elements}}
* @param elements the elements to filter
* @since 9
*/
@ -225,8 +212,7 @@ public class ElementFilter {
}
/**
* Returns a set of modules in {@code elements}.
* @return a set of modules in {@code elements}
* {@return a set of modules in {@code elements}}
* @param elements the elements to filter
* @since 9
*/
@ -261,8 +247,7 @@ public class ElementFilter {
}
/**
* Returns a list of {@code exports} directives in {@code directives}.
* @return a list of {@code exports} directives in {@code directives}
* {@return a list of {@code exports} directives in {@code directives}}
* @param directives the directives to filter
* @since 9
*/
@ -272,8 +257,7 @@ public class ElementFilter {
}
/**
* Returns a list of {@code opens} directives in {@code directives}.
* @return a list of {@code opens} directives in {@code directives}
* {@return a list of {@code opens} directives in {@code directives}}
* @param directives the directives to filter
* @since 9
*/
@ -283,8 +267,7 @@ public class ElementFilter {
}
/**
* Returns a list of {@code provides} directives in {@code directives}.
* @return a list of {@code provides} directives in {@code directives}
* {@return a list of {@code provides} directives in {@code directives}}
* @param directives the directives to filter
* @since 9
*/
@ -294,8 +277,7 @@ public class ElementFilter {
}
/**
* Returns a list of {@code requires} directives in {@code directives}.
* @return a list of {@code requires} directives in {@code directives}
* {@return a list of {@code requires} directives in {@code directives}}
* @param directives the directives to filter
* @since 9
*/
@ -305,8 +287,7 @@ public class ElementFilter {
}
/**
* Returns a list of {@code uses} directives in {@code directives}.
* @return a list of {@code uses} directives in {@code directives}
* {@return a list of {@code uses} directives in {@code directives}}
* @param directives the directives to filter
* @since 9
*/

39
src/java.compiler/share/classes/javax/lang/model/util/Elements.java
View File

@ -266,11 +266,10 @@ public interface Elements {
}
/**
* Returns the values of an annotation's elements, including defaults.
* {@return the values of an annotation's elements, including defaults}
*
* @see AnnotationMirror#getElementValues()
* @param a annotation to examine
* @return the values of the annotation's elements, including defaults
*/
Map<? extends ExecutableElement, ? extends AnnotationValue>
getElementValuesWithDefaults(AnnotationMirror a);
@ -302,15 +301,14 @@ public interface Elements {
String getDocComment(Element e);
/**
* Returns {@code true} if the element is deprecated, {@code false} otherwise.
* {@return {@code true} if the element is deprecated, {@code false} otherwise}
*
* @param e the element being examined
* @return {@code true} if the element is deprecated, {@code false} otherwise
*/
boolean isDeprecated(Element e);
/**
* Returns the <em>origin</em> of the given element.
* {@return the <em>origin</em> of the given element}
*
* <p>Note that if this method returns {@link Origin#EXPLICIT
* EXPLICIT} and the element was created from a class file, then
@ -326,7 +324,6 @@ public interface Elements {
* {@link Origin#EXPLICIT EXPLICIT}.
*
* @param e the element being examined
* @return the origin of the given element
* @since 9
*/
default Origin getOrigin(Element e) {
@ -334,7 +331,7 @@ public interface Elements {
}
/**
* Returns the <em>origin</em> of the given annotation mirror.
* {@return the <em>origin</em> of the given annotation mirror}
*
* An annotation mirror is {@linkplain Origin#MANDATED mandated}
* if it is an implicitly declared <em>container annotation</em>
@ -356,7 +353,6 @@ public interface Elements {
*
* @param c the construct the annotation mirror modifies
* @param a the annotation mirror being examined
* @return the origin of the given annotation mirror
* @jls 9.6.3 Repeatable Annotation Types
* @jls 9.7.5 Multiple Annotations of the Same Type
* @since 9
@ -367,7 +363,7 @@ public interface Elements {
}
/**
* Returns the <em>origin</em> of the given module directive.
* {@return the <em>origin</em> of the given module directive}
*
* <p>Note that if this method returns {@link Origin#EXPLICIT
* EXPLICIT} and the module directive was created from a class
@ -390,7 +386,6 @@ public interface Elements {
*
* @param m the module of the directive
* @param directive the module directive being examined
* @return the origin of the given directive
* @since 9
*/
default Origin getOrigin(ModuleElement m,
@ -457,14 +452,12 @@ public interface Elements {
}
/**
* Returns {@code true} if the executable element is a bridge
* method, {@code false} otherwise.
* {@return {@code true} if the executable element is a bridge
* method, {@code false} otherwise}
*
* @implSpec The default implementation of this method returns {@code false}.
*
* @param e the executable being examined
* @return {@code true} if the executable element is a bridge
* method, {@code false} otherwise
* @since 9
*/
default boolean isBridge(ExecutableElement e) {
@ -472,10 +465,9 @@ public interface Elements {
}
/**
* Returns the <i>binary name</i> of a type element.
* {@return the <i>binary name</i> of a type element}
*
* @param type the type element being examined
* @return the binary name
*
* @see TypeElement#getQualifiedName
* @jls 13.1 The Form of a Binary
@ -484,7 +476,7 @@ public interface Elements {
/**
* Returns the package of an element. The package of a package is
* {@return the package of an element} The package of a package is
* itself.
* The package of a module is {@code null}.
*
@ -494,12 +486,11 @@ public interface Elements {
* {@linkplain Element#getEnclosingElement enclosing element}.
*
* @param e the element being examined
* @return the package of an element
*/
PackageElement getPackageOf(Element e);
/**
* Returns the module of an element. The module of a module is
* {@return the module of an element} The module of a module is
* itself.
*
* If a package has a module as its {@linkplain
@ -522,7 +513,6 @@ public interface Elements {
* {@code null}.
*
* @param e the element being examined
* @return the module of an element
* @since 9
*/
default ModuleElement getModuleOf(Element e) {
@ -649,19 +639,18 @@ public interface Elements {
void printElements(java.io.Writer w, Element... elements);
/**
* Return a name with the same sequence of characters as the
* argument.
* {@return a name with the same sequence of characters as the
* argument}
*
* @param cs the character sequence to return as a name
* @return a name with the same sequence of characters as the argument
*/
Name getName(CharSequence cs);
/**
* Returns {@code true} if the type element is a functional interface, {@code false} otherwise.
* {@return {@code true} if the type element is a functional
* interface, {@code false} otherwise}
*
* @param type the type element being examined
* @return {@code true} if the element is a functional interface, {@code false} otherwise
* @jls 9.8 Functional Interfaces
* @since 1.8
*/

27
src/java.compiler/share/classes/javax/lang/model/util/Types.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2005, 2019, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2005, 2020, 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
@ -145,21 +145,19 @@ public interface Types {
List<? extends TypeMirror> directSupertypes(TypeMirror t);
/**
* Returns the erasure of a type.
* {@return the erasure of a type}
*
* @param t the type to be erased
* @return the erasure of the given type
* @throws IllegalArgumentException if given a type for a package or module
* @jls 4.6 Type Erasure
*/
TypeMirror erasure(TypeMirror t);
/**
* Returns the class of a boxed value of a given primitive type.
* {@return the class of a boxed value of the primitive type argument}
* That is, <i>boxing conversion</i> is applied.
*
* @param p the primitive type to be converted
* @return the class of a boxed value of type {@code p}
* @jls 5.1.7 Boxing Conversion
*/
TypeElement boxedClass(PrimitiveType p);
@ -187,18 +185,15 @@ public interface Types {
TypeMirror capture(TypeMirror t);
/**
* Returns a primitive type.
* {@return a primitive type}
*
* @param kind the kind of primitive type to return
* @return a primitive type
* @throws IllegalArgumentException if {@code kind} is not a primitive kind
*/
PrimitiveType getPrimitiveType(TypeKind kind);
/**
* Returns the null type. This is the type of {@code null}.
*
* @return the null type
* {@return the null type} This is the type of {@code null}.
*/
NullType getNullType();
@ -222,30 +217,28 @@ public interface Types {
NoType getNoType(TypeKind kind);
/**
* Returns an array type with the specified component type.
* {@return an array type with the specified component type}
*
* @param componentType the component type
* @return an array type with the specified component type.
* @throws IllegalArgumentException if the component type is not valid for
* an array
*/
ArrayType getArrayType(TypeMirror componentType);
/**
* Returns a new wildcard type argument. Either of the wildcard's
* {@return a new wildcard type} Either of the wildcard's
* bounds may be specified, or neither, but not both.
*
* @param extendsBound the extends (upper) bound, or {@code null} if none
* @param superBound the super (lower) bound, or {@code null} if none
* @return a new wildcard
* @throws IllegalArgumentException if bounds are not valid
*/
WildcardType getWildcardType(TypeMirror extendsBound,
TypeMirror superBound);
/**
* Returns the type corresponding to a type element and
* actual type arguments.
* {@return the type corresponding to a type element and
* actual type arguments}
* Given the type element for {@code Set} and the type mirror
* for {@code String},
* for example, this method may be used to get the
@ -265,8 +258,6 @@ public interface Types {
*
* @param typeElem the type element
* @param typeArgs the actual type arguments
* @return the type corresponding to the type element and
* actual type arguments
* @throws IllegalArgumentException if too many or too few
* type arguments are given, or if an inappropriate type
* argument or type element is provided