From c77e6939a0bbbbe2816142727239a1868d99aecc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=90=D0=BB=D0=B5=D0=BA=D1=81=D0=B0=D0=BD=D0=B4=D1=8A?= =?UTF-8?q?=D1=80=20=D0=9A=D1=83=D1=80=D1=82=D0=B0=D0=BA=D0=BE=D0=B2?= Date: Thu, 9 Jan 2025 13:05:51 +0200 Subject: [PATCH] Improve AST and ASTParser classes javadoc * Use getJLSLatest in docs instead of JLS12 as preferred value * Mention getJLSLatest in more places to make it more visible * Improve lists ending at Java 14 or 17 to actually be ranges up to 23 without listing all values as this makes documentation needlessly big * Add Deprecated annotation in addition to the javadoc tag --- .../dom/org/eclipse/jdt/core/dom/AST.java | 42 +++++++++++++------ .../org/eclipse/jdt/core/dom/ASTParser.java | 7 ++-- 2 files changed, 32 insertions(+), 17 deletions(-) diff --git a/org.eclipse.jdt.core/dom/org/eclipse/jdt/core/dom/AST.java b/org.eclipse.jdt.core/dom/org/eclipse/jdt/core/dom/AST.java index fddc84e74f8..5e77b288366 100644 --- a/org.eclipse.jdt.core/dom/org/eclipse/jdt/core/dom/AST.java +++ b/org.eclipse.jdt.core/dom/org/eclipse/jdt/core/dom/AST.java @@ -1,5 +1,5 @@ /******************************************************************************* - * Copyright (c) 2000, 2024 IBM Corporation and others. + * Copyright (c) 2000, 2025 IBM Corporation and others. * * This program and the accompanying materials * are made available under the terms of the Eclipse Public License 2.0 @@ -124,6 +124,7 @@ public final class AST { * @since 3.0 * @deprecated Clients should use the {@link #getJLSLatest()} AST API instead. */ + @Deprecated public static final int JLS2 = 2; /** @@ -148,6 +149,7 @@ public final class AST { * @since 3.1 * @deprecated Clients should use the {@link #getJLSLatest()} AST API instead. */ + @Deprecated public static final int JLS3 = 3; /** @@ -172,6 +174,7 @@ public final class AST { * @since 3.7.1 * @deprecated Clients should use the {@link #getJLSLatest()} AST API instead. */ + @Deprecated public static final int JLS4 = 4; /** @@ -196,6 +199,7 @@ public final class AST { * @since 3.10 * @deprecated Clients should use the {@link #getJLSLatest()} AST API instead. */ + @Deprecated public static final int JLS8 = 8; /** @@ -220,6 +224,7 @@ public final class AST { * @since 3.14 * @deprecated Clients should use the {@link #getJLSLatest()} AST API instead. */ + @Deprecated public static final int JLS9 = 9; /** @@ -244,6 +249,7 @@ public final class AST { * @since 3.14 * @deprecated Clients should use the {@link #getJLSLatest()} AST API instead. */ + @Deprecated public static final int JLS10 = 10; /** @@ -268,6 +274,7 @@ public final class AST { * @deprecated Clients should use the {@link #getJLSLatest()} AST API instead. * @since 3.16 */ + @Deprecated public static final int JLS11 = 11; /** @@ -291,6 +298,7 @@ public final class AST { * @deprecated Clients should use the {@link #getJLSLatest()} AST API instead. * @since 3.18 */ + @Deprecated public static final int JLS12 = 12; /** * Internal synonym for {@link #JLS12}. Use to alleviate @@ -312,8 +320,8 @@ public final class AST { *

* @deprecated Clients should use the {@link #getJLSLatest()} AST API instead. * @since 3.20 - * @deprecated Clients should use the {@link #getJLSLatest()} AST API instead. */ + @Deprecated public static final int JLS13 = 13; /** @@ -337,6 +345,7 @@ public final class AST { * @deprecated Clients should use the {@link #getJLSLatest()} AST API instead. * @since 3.22 */ + @Deprecated public static final int JLS14 = 14; /** @@ -360,6 +369,7 @@ public final class AST { * @deprecated Clients should use the {@link #getJLSLatest()} AST API instead. * @since 3.24 */ + @Deprecated public static final int JLS15 = 15; /** * Constant for indicating the AST API that handles JLS16. @@ -375,6 +385,7 @@ public final class AST { * @deprecated Clients should use the {@link #getJLSLatest()} AST API instead. * @since 3.26 */ + @Deprecated public static final int JLS16 = 16; /** * Constant for indicating the AST API that handles JLS17. @@ -390,6 +401,7 @@ public final class AST { * @deprecated Clients should use the {@link #getJLSLatest()} AST API instead. * @since 3.28 */ + @Deprecated public static final int JLS17 = 17; /** * Constant for indicating the AST API that handles JLS17. @@ -406,6 +418,7 @@ public final class AST { * @deprecated * @since 3.30 */ + @Deprecated public static final int JLS18 = 18; /** @@ -423,6 +436,7 @@ public final class AST { * @deprecated * @since 3.32 */ + @Deprecated public static final int JLS19 = 19; /** @@ -541,6 +555,7 @@ public final class AST { * This provides the latest JLS level. * @deprecated use {@link #getJLSLatest()} */ + @Deprecated public static final int JLS_Latest = JLS_INTERNAL_Latest; /* @@ -652,7 +667,7 @@ public static CompilationUnit convertCompilationUnit( * Creates a new Java abstract syntax tree * (AST) following the specified set of API rules. *

- * Clients should use this method specifying {@link #JLS12} as the + * Clients should use this method specifying {@link #getJLSLatest} as the * AST level in all cases, even when dealing with source of earlier JDK versions like 1.3 or 1.4. *

* @@ -663,9 +678,10 @@ public static CompilationUnit convertCompilationUnit( *
  • the API level is not one of the JLS* level constants
    • * * @deprecated Clients should port their code to use the latest JLS* AST API and call - * {@link #newAST(int, boolean) AST.newAST(AST.JLS12, false)} instead of using this constructor. + * {@link #newAST(int, boolean) AST.newAST(AST.getJLSLatest(), false)} instead of using this constructor. * @since 3.0 */ + @Deprecated public static AST newAST(int level) { return new AST(level, false); } @@ -674,11 +690,11 @@ public static AST newAST(int level) { * Creates a new Java abstract syntax tree * (AST) following the specified set of API rules. *

    - * Clients should use this method specifying {@link #JLS12} as the + * Clients should use this method specifying {@link #getJLSLatest} as the * AST level in all cases, even when dealing with source of earlier JDK versions like 1.3 or 1.4. *

    * - * @param level the API level; one of the JLS* level constants + * @param level the API level; one of the JLS* level constants or {@link AST#getJLSLatest} * @param previewEnabled true if preview feature is enabled else false * @return new AST instance following the specified set of API rules. * @exception IllegalArgumentException if: @@ -702,8 +718,8 @@ public static AST newAST(int level, boolean previewEnabled) { * "1.3" means the source code is as per JDK 1.3 and api level {@link #JLS3}. *
  • "1.4", "1.5", "1.6", "1.7" "1.8" implies the respective source JDK levels 1.4, 1.5, 1.6, 1.7 and api level {@link #JLS4}.
    • *
  • "1.8" implies the respective source JDK level 1.8 and api level {@link #JLS8}.
    • - *
  • "9", "10", "11", "12" and "13" implies the respective JDK levels 9, 10, 11, 12 and 13 - * and api levels {@link #JLS9}, {@link #JLS10}, {@link #JLS11}, {@link #JLS12} and {@link #JLS13}.
    • + *
  • "9", "10", "11" up to "23" implies the respective JDK levels 9, 10, 11 up to 23 + * and api levels {@link #JLS9}, {@link #JLS10}, {@link #JLS11} up to {@link #JLS23}.
    • *
  • Additional legal values may be added later.
    • * * @@ -1088,8 +1104,9 @@ public static CompilationUnit parseCompilationUnit( * * @see JavaCore#getDefaultOptions() * @deprecated Clients should port their code to use the latest JLS* AST API and call - * {@link #newAST(int, boolean) AST.newAST(AST.JLS12, false)} instead of using this constructor. + * {@link #newAST(int, boolean) AST.newAST(AST.getJLSLatest, false)} instead of using this constructor. */ + @Deprecated public AST() { this(JavaCore.getDefaultOptions()); } @@ -1207,11 +1224,10 @@ private AST(int level, boolean previewEnabled) { * *
  • "org.eclipse.jdt.core.compiler.problem.enablePreviewFeatures" - diff --git a/org.eclipse.jdt.core/dom/org/eclipse/jdt/core/dom/ASTParser.java b/org.eclipse.jdt.core/dom/org/eclipse/jdt/core/dom/ASTParser.java index a156cd00975..6223e6f1aaa 100644 --- a/org.eclipse.jdt.core/dom/org/eclipse/jdt/core/dom/ASTParser.java +++ b/org.eclipse.jdt.core/dom/org/eclipse/jdt/core/dom/ASTParser.java @@ -1,5 +1,5 @@ /******************************************************************************* - * Copyright (c) 2004, 2022 IBM Corporation and others. + * Copyright (c) 2004, 2025 IBM Corporation and others. * * This program and the accompanying materials * are made available under the terms of the Eclipse Public License 2.0 @@ -128,8 +128,7 @@ public class ASTParser { * Creates a new object for creating a Java abstract syntax tree * (AST) following the specified set of API rules. * - * @param level the API level; one of the .JLS* level constants - * declared on {@link AST} + * @param level the API level; one of the .JLS* level constants declared on {@link AST} or {@link AST#getJLSLatest} * @return new ASTParser instance */ public static ASTParser newParser(int level) { @@ -227,7 +226,7 @@ public static ASTParser newParser(int level) { *

    * * @param level the API level; one of the JLS* level constants - * declared on {@link AST} + * declared on {@link AST} or {@link AST#getJLSLatest()} */ ASTParser(int level) { DOMASTUtil.checkASTLevel(level);