[javascript] Add deprecations for EcmascriptParser/Handler

Refs #2837

docs/pages/release_notes.md

@@ -24,7 +24,20 @@ This is a {{ site.pmd.release_type }} release.
 
 #### Deprecated API
 
-- {% jdoc java::ast.ASTPackageDeclaration#getPackageNameImage() %}, {% jdoc java::ast.ASTTypeParameter#getParameterName() %} and the corresponding XPath attributes. In both cases they're replaced with a new method `getName`, the attribute is `@Name`
+*   {% jdoc java::ast.ASTPackageDeclaration#getPackageNameImage() %}, {% jdoc java::ast.ASTTypeParameter#getParameterName() %}
+    and the corresponding XPath attributes. In both cases they're replaced with a new method `getName`,
+    the attribute is `@Name`.
+
+##### Internal API
+
+Those APIs are not intended to be used by clients, and will be hidden or removed with PMD 7.0.0.
+You can identify them with the `@InternalApi` annotation. You'll also get a deprecation warning.
+
+*   {% jdoc !!javascript::lang.ecmascript.Ecmascript3Handler %}
+*   {% jdoc !!javascript::lang.ecmascript.Ecmascript3Parser %}
+*   {% jdoc !!javascript::lang.ecmascript.ast.EcmascriptParser#parserOptions %}
+*   {% jdoc !!javascript::lang.ecmascript.ast.EcmascriptParser#getSuppressMap() %}
+
 
 ### External Contributions
 

pmd-javascript/src/main/java/net/sourceforge/pmd/lang/ecmascript/Ecmascript3Handler.java

@@ -6,7 +6,9 @@ package net.sourceforge.pmd.lang.ecmascript;
 
 import java.io.Writer;
 
+import net.sourceforge.pmd.annotation.InternalApi;
 import net.sourceforge.pmd.lang.AbstractLanguageVersionHandler;
+import net.sourceforge.pmd.lang.LanguageVersionHandler;
 import net.sourceforge.pmd.lang.Parser;
 import net.sourceforge.pmd.lang.ParserOptions;
 import net.sourceforge.pmd.lang.VisitorStarter;
@@ -18,7 +20,11 @@ import net.sourceforge.pmd.lang.rule.RuleViolationFactory;
 
 /**
  * Implementation of LanguageVersionHandler for the ECMAScript Version 3.
+ *
+ * @deprecated This is internal API, use {@link LanguageVersionHandler#getParser(ParserOptions)}.
  */
+@InternalApi
+@Deprecated
 public class Ecmascript3Handler extends AbstractLanguageVersionHandler {
 
     @Override

pmd-javascript/src/main/java/net/sourceforge/pmd/lang/ecmascript/Ecmascript3Parser.java

@@ -7,7 +7,9 @@ package net.sourceforge.pmd.lang.ecmascript;
 import java.io.Reader;
 import java.util.Map;
 
+import net.sourceforge.pmd.annotation.InternalApi;
 import net.sourceforge.pmd.lang.AbstractParser;
+import net.sourceforge.pmd.lang.LanguageVersionHandler;
 import net.sourceforge.pmd.lang.ParserOptions;
 import net.sourceforge.pmd.lang.TokenManager;
 import net.sourceforge.pmd.lang.ast.Node;
@@ -16,7 +18,11 @@ import net.sourceforge.pmd.lang.ecmascript5.Ecmascript5TokenManager;
 
 /**
  * Adapter for the EcmascriptParser.
+ *
+ * @deprecated This is internal API, use {@link LanguageVersionHandler#getParser(ParserOptions)}.
  */
+@InternalApi
+@Deprecated
 public class Ecmascript3Parser extends AbstractParser {
     private net.sourceforge.pmd.lang.ecmascript.ast.EcmascriptParser ecmascriptParser;
 

pmd-javascript/src/main/java/net/sourceforge/pmd/lang/ecmascript/EcmascriptParserOptions.java

@@ -9,12 +9,14 @@ import java.util.Objects;
 import org.mozilla.javascript.Context;
 
 import net.sourceforge.pmd.Rule;
+import net.sourceforge.pmd.lang.LanguageVersionHandler;
 import net.sourceforge.pmd.lang.ParserOptions;
 import net.sourceforge.pmd.properties.BooleanProperty;
 import net.sourceforge.pmd.properties.EnumeratedProperty;
 
 /**
  * @deprecated Will be removed in 7.0 TODO refactor this into language versions?
+ *             In PMD 6, use {@link LanguageVersionHandler#getDefaultParserOptions()} instead.
  */
 @Deprecated
 public class EcmascriptParserOptions extends ParserOptions {

pmd-javascript/src/main/java/net/sourceforge/pmd/lang/ecmascript/ast/EcmascriptParser.java

@@ -19,10 +19,13 @@ import org.mozilla.javascript.ast.Comment;
 import org.mozilla.javascript.ast.ErrorCollector;
 import org.mozilla.javascript.ast.ParseProblem;
 
+import net.sourceforge.pmd.annotation.InternalApi;
 import net.sourceforge.pmd.lang.ast.ParseException;
 import net.sourceforge.pmd.lang.ecmascript.EcmascriptParserOptions;
 
 public class EcmascriptParser {
+    @Deprecated
+    @InternalApi
     protected final EcmascriptParserOptions parserOptions;
 
     private Map<Integer, String> suppressMap;
@@ -83,6 +86,8 @@ public class EcmascriptParser {
         }
     }
 
+    @Deprecated
+    @InternalApi
     public Map<Integer, String> getSuppressMap() {
         return suppressMap;
     }