Skip to content

Commit

Permalink
Improve AST and ASTParser classes javadoc
Browse files Browse the repository at this point in the history 
* 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
  • Loading branch information
@akurtakov
akurtakov committed Jan 9, 2025
1 parent 460ebc3 commit c77e693
Show file tree
Hide file tree
Showing 2 changed files with 32 additions and 17 deletions.
42 changes: 29 additions & 13 deletions org.eclipse.jdt.core/dom/org/eclipse/jdt/core/dom/AST.java
View file
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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;

/**
Expand All @@ -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;

/**
Expand All @@ -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;

/**
Expand All @@ -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;

/**
Expand All @@ -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;

/**
Expand All @@ -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;

/**
Expand All @@ -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;

/**
Expand All @@ -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
Expand All @@ -312,8 +320,8 @@ public final class AST {
* </p>
* @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;

/**
Expand All @@ -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;

/**
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -406,6 +418,7 @@ public final class AST {
* @deprecated
* @since 3.30
*/
@Deprecated
public static final int JLS18 = 18;

/**
Expand All @@ -423,6 +436,7 @@ public final class AST {
* @deprecated
* @since 3.32
*/
@Deprecated
public static final int JLS19 = 19;

/**
Expand Down Expand Up @@ -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;

/*
Expand Down Expand Up @@ -652,7 +667,7 @@ public static CompilationUnit convertCompilationUnit(
* Creates a new Java abstract syntax tree
* (AST) following the specified set of API rules.
* <p>
* 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.
* </p>
*
Expand All @@ -663,9 +678,10 @@ public static CompilationUnit convertCompilationUnit(
* <li>the API level is not one of the <code>JLS*</code> level constants</li>
* </ul>
* @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);
}
Expand All @@ -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.
* <p>
* 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.
* </p>
*
* @param level the API level; one of the <code>JLS*</code> level constants
* @param level the API level; one of the <code>JLS*</code> level constants or {@link AST#getJLSLatest}
* @param previewEnabled <code>true</code> if preview feature is enabled else <code>false</code>
* @return new AST instance following the specified set of API rules.
* @exception IllegalArgumentException if:
Expand All @@ -702,8 +718,8 @@ public static AST newAST(int level, boolean previewEnabled) {
* <code>"1.3"</code> means the source code is as per JDK 1.3 and api level {@link #JLS3}.</li>
* <li><code>"1.4", "1.5", "1.6", "1.7" "1.8"</code> implies the respective source JDK levels 1.4, 1.5, 1.6, 1.7 and api level {@link #JLS4}.</li>
* <li><code>"1.8"</code> implies the respective source JDK level 1.8 and api level {@link #JLS8}.</li>
* <li><code>"9", "10", "11", "12" and "13"</code> 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}.</li>
* <li><code>"9", "10", "11" up to "23"</code> implies the respective JDK levels 9, 10, 11 up to 23
* and api levels {@link #JLS9}, {@link #JLS10}, {@link #JLS11} up to {@link #JLS23}.</li>
* <li>Additional legal values may be added later.</li>
* </ul>
* </li>
Expand Down Expand Up @@ -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());
}
Expand Down Expand Up @@ -1207,11 +1224,10 @@ private AST(int level, boolean previewEnabled) {
* <ul>
* <li>
* <code>"1.3"</code> means the source code is as per JDK 1.3 and api level {@link #JLS3}.</li>
* <li><code>"1.4", "1.5", "1.6", "1.7" "1.8"</code> implies the respective source JDK levels 1.4, 1.5, 1.6, 1.7 and api level {@link #JLS4}.</li>
* <li><code>"1.4", "1.5", "1.6", "1.7"</code> implies the respective source JDK levels 1.4, 1.5, 1.6, 1.7 and api level {@link #JLS4}.</li>
* <li><code>"1.8"</code> implies the respective source JDK level 1.8 and api level {@link #JLS8}.</li>
* <li><code>"9", "10", "11", "12", "13", "14", "15", "16" and "17"</code> implies the respective JDK levels 9, 10, 11, 12, 13, 14, 15, 16 and 17
* and api levels {@link #JLS9}, {@link #JLS10}, {@link #JLS11}, {@link #JLS12}, {@link #JLS13}
* {@link #JLS14}, {@link #JLS15}, {@link #JLS16} and {@link #JLS17}.</li>
* <li><code>"9", "10", "11" up to "23"</code> implies the respective JDK levels 9, 10, 11 up to 23
* and api levels {@link #JLS9}, {@link #JLS10}, {@link #JLS11} up to {@link #JLS23}.</li>
* <li>Additional legal values may be added later.</li>
* </ul>
* <li><code>"org.eclipse.jdt.core.compiler.problem.enablePreviewFeatures"</code> -
Expand Down
7 changes: 3 additions & 4 deletions org.eclipse.jdt.core/dom/org/eclipse/jdt/core/dom/ASTParser.java
View file
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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 <code>.JLS*</code> level constants
* declared on {@link AST}
* @param level the API level; one of the <code>.JLS*</code> level constants declared on {@link AST} or {@link AST#getJLSLatest}
* @return new ASTParser instance
*/
public static ASTParser newParser(int level) {
Expand Down Expand Up @@ -227,7 +226,7 @@ public static ASTParser newParser(int level) {
* </p>
*
* @param level the API level; one of the <code>JLS*</code> level constants
* declared on {@link AST}
* declared on {@link AST} or {@link AST#getJLSLatest()}
*/
ASTParser(int level) {
DOMASTUtil.checkASTLevel(level);
Expand Down

0 comments on commit c77e693

Please sign in to comment.