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

Reviewed-by: jjg, iris

Author: jddarcy

src/java.compiler/share/classes/javax/annotation/processing/AbstractProcessor.java

@@ -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 boolean process(Set<? extends TypeElement> annotations,
                                     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 Iterable<? extends Completion> getCompletions(Element element,
     }
 
     /**
-     * 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;

src/java.compiler/share/classes/javax/annotation/processing/Completion.java

@@ -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 @@
 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();
 }

src/java.compiler/share/classes/javax/annotation/processing/Completions.java

@@ -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 String toString() {
     }
 
     /**
-     * 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, "");

src/java.compiler/share/classes/javax/annotation/processing/ProcessingEnvironment.java

@@ -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 @@
  */
 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();
 

src/java.compiler/share/classes/javax/annotation/processing/Processor.java

@@ -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
      */

src/java.compiler/share/classes/javax/annotation/processing/RoundEnvironment.java

@@ -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 @@
  */
 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();
 

src/java.compiler/share/classes/javax/annotation/processing/SupportedAnnotationTypes.java

@@ -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 @@
 @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();
 }

src/java.compiler/share/classes/javax/annotation/processing/SupportedOptions.java

@@ -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 @@
 @Retention(RUNTIME)
 public @interface SupportedOptions {
     /**
-     * Returns the supported options.
-     * @return the supported options
+     * {@return the supported options}
      */
     String [] value();
 }

src/java.compiler/share/classes/javax/annotation/processing/SupportedSourceVersion.java

@@ -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 @@
 @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();
 }

src/java.compiler/share/classes/javax/lang/model/AnnotatedConstruct.java

@@ -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

src/java.compiler/share/classes/javax/lang/model/SourceVersion.java

@@ -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 @@ private static SourceVersion getLatestSupported() {
     }
 
     /**
-     * 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 @@ private static SourceVersion getLatestSupported() {
      * 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;

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

@@ -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 @@
 public interface AnnotationMirror {
 
     /**
-     * Returns the type of this annotation.
-     *
-     * @return the type of this annotation
+     * {@return the type of this annotation}
      */
     DeclaredType getAnnotationType();
 

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

@@ -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 @@
 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();