From fae522a002497b598d288cfceb66e28bf0d88632 Mon Sep 17 00:00:00 2001
From: Andreas Dangel <andreas.dangel@pmd-code.org>
Date: Thu, 1 Feb 2024 12:09:12 +0100
Subject: [PATCH] [core] Unify javadoc for InternalApiBridge classes

Refs #4348
---
 .../sourceforge/pmd/ant/InternalApiBridge.java  | 12 ++++++++----
 .../lang/apex/multifile/InternalApiBridge.java  | 12 +++++++++---
 .../net/sourceforge/pmd/InternalApiBridge.java  | 12 ++++++++----
 .../sourceforge/pmd/lang/InternalApiBridge.java |  8 ++++++++
 .../pmd/lang/java/ast/InternalApiBridge.java    | 11 +++++------
 .../pmd/lang/java/types/InternalApiBridge.java  | 12 +++++++++---
 .../lang/java/types/ast/InternalApiBridge.java  | 12 +++++++++---
 .../pmd/lang/jsp/ast/InternalApiBridge.java     | 12 +++++++++---
 .../lang/modelica/ast/InternalApiBridge.java    | 11 +++++++++++
 .../modelica/resolver/InternalApiBridge.java    | 11 +++++++++++
 .../pmd/lang/plsql/ast/InternalApiBridge.java   | 17 ++++++++++-------
 .../pmd/lang/vf/ast/InternalApiBridge.java      | 15 ++++++++++-----
 12 files changed, 107 insertions(+), 38 deletions(-)

diff --git a/pmd-ant/src/main/java/net/sourceforge/pmd/ant/InternalApiBridge.java b/pmd-ant/src/main/java/net/sourceforge/pmd/ant/InternalApiBridge.java
index 0aa1b05065..604e9c3997 100644
--- a/pmd-ant/src/main/java/net/sourceforge/pmd/ant/InternalApiBridge.java
+++ b/pmd-ant/src/main/java/net/sourceforge/pmd/ant/InternalApiBridge.java
@@ -12,15 +12,19 @@ import net.sourceforge.pmd.annotation.InternalApi;
 import net.sourceforge.pmd.reporting.GlobalAnalysisListener;
 
 /**
- * Gives access to package private methods.
+ * Internal API.
+ *
+ * <p>Acts as a bridge between outer parts of PMD and the restricted access
+ * internal API of this package.
+ *
+ * <p><b>None of this is published API, and compatibility can be broken anytime!</b>
+ * Use this only at your own risk.
  *
  * @apiNote Internal API
  */
 @InternalApi
 public final class InternalApiBridge {
-    private InternalApiBridge() {
-        // utility class
-    }
+    private InternalApiBridge() {}
 
     public static GlobalAnalysisListener newListener(Formatter formatter, Project project) throws IOException {
         return formatter.newListener(project);
diff --git a/pmd-apex/src/main/java/net/sourceforge/pmd/lang/apex/multifile/InternalApiBridge.java b/pmd-apex/src/main/java/net/sourceforge/pmd/lang/apex/multifile/InternalApiBridge.java
index 3a3d2643af..beba36c4f7 100644
--- a/pmd-apex/src/main/java/net/sourceforge/pmd/lang/apex/multifile/InternalApiBridge.java
+++ b/pmd-apex/src/main/java/net/sourceforge/pmd/lang/apex/multifile/InternalApiBridge.java
@@ -8,13 +8,19 @@ import net.sourceforge.pmd.annotation.InternalApi;
 import net.sourceforge.pmd.lang.apex.ApexLanguageProperties;
 
 /**
+ * Internal API.
+ *
+ * <p>Acts as a bridge between outer parts of PMD and the restricted access
+ * internal API of this package.
+ *
+ * <p><b>None of this is published API, and compatibility can be broken anytime!</b>
+ * Use this only at your own risk.
+ *
  * @apiNote Internal API
  */
 @InternalApi
 public final class InternalApiBridge {
-    private InternalApiBridge() {
-        // utility class
-    }
+    private InternalApiBridge() {}
 
     public static ApexMultifileAnalysis createApexMultiFileAnalysis(ApexLanguageProperties properties) {
         return new ApexMultifileAnalysis(properties);
diff --git a/pmd-core/src/main/java/net/sourceforge/pmd/InternalApiBridge.java b/pmd-core/src/main/java/net/sourceforge/pmd/InternalApiBridge.java
index 118664ccc4..60be0d4447 100644
--- a/pmd-core/src/main/java/net/sourceforge/pmd/InternalApiBridge.java
+++ b/pmd-core/src/main/java/net/sourceforge/pmd/InternalApiBridge.java
@@ -8,15 +8,19 @@ import net.sourceforge.pmd.annotation.InternalApi;
 import net.sourceforge.pmd.reporting.FileAnalysisListener;
 
 /**
- * Makes package private methods available for other packages. This is only internal.
+ * Internal API.
+ *
+ * <p>Acts as a bridge between outer parts of PMD and the restricted access
+ * internal API of this package.
+ *
+ * <p><b>None of this is published API, and compatibility can be broken anytime!</b>
+ * Use this only at your own risk.
  *
  * @apiNote Internal API
  */
 @InternalApi
 public final class InternalApiBridge {
-    private InternalApiBridge() {
-        // utility class
-    }
+    private InternalApiBridge() {}
 
     public static Rule getRule(RuleContext ruleContext) {
         return ruleContext.getRule();
diff --git a/pmd-core/src/main/java/net/sourceforge/pmd/lang/InternalApiBridge.java b/pmd-core/src/main/java/net/sourceforge/pmd/lang/InternalApiBridge.java
index fe139d6d9e..7a7618e264 100644
--- a/pmd-core/src/main/java/net/sourceforge/pmd/lang/InternalApiBridge.java
+++ b/pmd-core/src/main/java/net/sourceforge/pmd/lang/InternalApiBridge.java
@@ -15,6 +15,14 @@ import net.sourceforge.pmd.util.log.PmdReporter;
 
 /**
  * Internal API.
+ *
+ * <p>Acts as a bridge between outer parts of PMD and the restricted access
+ * internal API of this package.
+ *
+ * <p><b>None of this is published API, and compatibility can be broken anytime!</b>
+ * Use this only at your own risk.
+ *
+ * @apiNote Internal API
  */
 @InternalApi
 public final class InternalApiBridge {
diff --git a/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/ast/InternalApiBridge.java b/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/ast/InternalApiBridge.java
index f1558ae801..f4bd52c36b 100644
--- a/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/ast/InternalApiBridge.java
+++ b/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/ast/InternalApiBridge.java
@@ -35,7 +35,9 @@ import net.sourceforge.pmd.lang.java.types.internal.infer.TypeInferenceLogger;
 import net.sourceforge.pmd.util.AssertionUtil;
 
 /**
- * Acts as a bridge between outer parts of PMD and the restricted access
+ * Internal API.
+ *
+ * <p>Acts as a bridge between outer parts of PMD and the restricted access
  * internal API of this package.
  *
  * <p><b>None of this is published API, and compatibility can be broken anytime!</b>
@@ -43,14 +45,11 @@ import net.sourceforge.pmd.util.AssertionUtil;
  *
  * @author Clément Fournier
  * @since 7.0.0
+ * @apiNote Internal API
  */
 @InternalApi
 public final class InternalApiBridge {
-
-
-    private InternalApiBridge() {
-
-    }
+    private InternalApiBridge() {}
 
     @Deprecated
     public static ASTVariableId newVarId(String image) {
diff --git a/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/types/InternalApiBridge.java b/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/types/InternalApiBridge.java
index e7bd326423..c5c19bcf50 100644
--- a/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/types/InternalApiBridge.java
+++ b/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/types/InternalApiBridge.java
@@ -7,13 +7,19 @@ package net.sourceforge.pmd.lang.java.types;
 import net.sourceforge.pmd.annotation.InternalApi;
 
 /**
+ * Internal API.
+ *
+ * <p>Acts as a bridge between outer parts of PMD and the restricted access
+ * internal API of this package.
+ *
+ * <p><b>None of this is published API, and compatibility can be broken anytime!</b>
+ * Use this only at your own risk.
+ *
  * @apiNote Internal API
  */
 @InternalApi
 public final class InternalApiBridge {
-    private InternalApiBridge() {
-        // internal api
-    }
+    private InternalApiBridge() {}
 
     public static boolean isSameTypeInInference(JTypeMirror t, JTypeMirror s) {
         return TypeOps.isSameTypeInInference(t, s);
diff --git a/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/types/ast/InternalApiBridge.java b/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/types/ast/InternalApiBridge.java
index 201fb2ee05..5b28467a0e 100644
--- a/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/types/ast/InternalApiBridge.java
+++ b/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/types/ast/InternalApiBridge.java
@@ -14,13 +14,19 @@ import net.sourceforge.pmd.lang.java.types.ast.internal.RegularCtx;
 import net.sourceforge.pmd.util.AssertionUtil;
 
 /**
+ * Internal API.
+ *
+ * <p>Acts as a bridge between outer parts of PMD and the restricted access
+ * internal API of this package.
+ *
+ * <p><b>None of this is published API, and compatibility can be broken anytime!</b>
+ * Use this only at your own risk.
+ *
  * @apiNote Internal API
  */
 @InternalApi
 public final class InternalApiBridge {
-    private InternalApiBridge() {
-        // utility
-    }
+    private InternalApiBridge() {}
 
     public static boolean canGiveContextToPoly(ExprContext exprContext, boolean lambdaOrMethodRef) {
         return exprContext.canGiveContextToPoly(lambdaOrMethodRef);
diff --git a/pmd-jsp/src/main/java/net/sourceforge/pmd/lang/jsp/ast/InternalApiBridge.java b/pmd-jsp/src/main/java/net/sourceforge/pmd/lang/jsp/ast/InternalApiBridge.java
index abd8e3db3a..ec6966ef08 100644
--- a/pmd-jsp/src/main/java/net/sourceforge/pmd/lang/jsp/ast/InternalApiBridge.java
+++ b/pmd-jsp/src/main/java/net/sourceforge/pmd/lang/jsp/ast/InternalApiBridge.java
@@ -8,13 +8,19 @@ import net.sourceforge.pmd.annotation.InternalApi;
 import net.sourceforge.pmd.lang.ast.impl.javacc.JavaccTokenDocument;
 
 /**
+ * Internal API.
+ *
+ * <p>Acts as a bridge between outer parts of PMD and the restricted access
+ * internal API of this package.
+ *
+ * <p><b>None of this is published API, and compatibility can be broken anytime!</b>
+ * Use this only at your own risk.
+ *
  * @apiNote Internal API
  */
 @InternalApi
 public final class InternalApiBridge {
-    private InternalApiBridge() {
-        // internal
-    }
+    private InternalApiBridge() {}
 
     public static JavaccTokenDocument.TokenDocumentBehavior getJspTokenBehavior() {
         return JspParser.TOKEN_BEHAVIOR;
diff --git a/pmd-modelica/src/main/java/net/sourceforge/pmd/lang/modelica/ast/InternalApiBridge.java b/pmd-modelica/src/main/java/net/sourceforge/pmd/lang/modelica/ast/InternalApiBridge.java
index a7b5aa41b5..475f5d046c 100644
--- a/pmd-modelica/src/main/java/net/sourceforge/pmd/lang/modelica/ast/InternalApiBridge.java
+++ b/pmd-modelica/src/main/java/net/sourceforge/pmd/lang/modelica/ast/InternalApiBridge.java
@@ -10,6 +10,17 @@ import net.sourceforge.pmd.lang.modelica.resolver.ModelicaScope;
 import net.sourceforge.pmd.lang.modelica.resolver.internal.ResolutionContext;
 import net.sourceforge.pmd.lang.modelica.resolver.internal.Watchdog;
 
+/**
+ * Internal API.
+ *
+ * <p>Acts as a bridge between outer parts of PMD and the restricted access
+ * internal API of this package.
+ *
+ * <p><b>None of this is published API, and compatibility can be broken anytime!</b>
+ * Use this only at your own risk.
+ *
+ * @apiNote Internal API
+ */
 @InternalApi
 public final class InternalApiBridge {
     private InternalApiBridge() {}
diff --git a/pmd-modelica/src/main/java/net/sourceforge/pmd/lang/modelica/resolver/InternalApiBridge.java b/pmd-modelica/src/main/java/net/sourceforge/pmd/lang/modelica/resolver/InternalApiBridge.java
index 5bf71e8346..0ae2528490 100644
--- a/pmd-modelica/src/main/java/net/sourceforge/pmd/lang/modelica/resolver/InternalApiBridge.java
+++ b/pmd-modelica/src/main/java/net/sourceforge/pmd/lang/modelica/resolver/InternalApiBridge.java
@@ -11,6 +11,17 @@ import net.sourceforge.pmd.lang.modelica.ast.Visibility;
 import net.sourceforge.pmd.lang.modelica.resolver.internal.ResolutionContext;
 import net.sourceforge.pmd.lang.modelica.resolver.internal.Watchdog;
 
+/**
+ * Internal API.
+ *
+ * <p>Acts as a bridge between outer parts of PMD and the restricted access
+ * internal API of this package.
+ *
+ * <p><b>None of this is published API, and compatibility can be broken anytime!</b>
+ * Use this only at your own risk.
+ *
+ * @apiNote Internal API
+ */
 @InternalApi
 public final class InternalApiBridge {
     private InternalApiBridge() {}
diff --git a/pmd-plsql/src/main/java/net/sourceforge/pmd/lang/plsql/ast/InternalApiBridge.java b/pmd-plsql/src/main/java/net/sourceforge/pmd/lang/plsql/ast/InternalApiBridge.java
index c9ef5160b7..bb63f354e4 100644
--- a/pmd-plsql/src/main/java/net/sourceforge/pmd/lang/plsql/ast/InternalApiBridge.java
+++ b/pmd-plsql/src/main/java/net/sourceforge/pmd/lang/plsql/ast/InternalApiBridge.java
@@ -10,17 +10,20 @@ import net.sourceforge.pmd.lang.symboltable.NameDeclaration;
 import net.sourceforge.pmd.lang.symboltable.Scope;
 
 /**
- * Acts as a bridge between outer parts (e.g. symbol table) and the restricted
- * access internal API of this package.
- * 
- * @apiNote  This is internal API.
+ * Internal API.
+ *
+ * <p>Acts as a bridge between outer parts of PMD and the restricted access
+ * internal API of this package.
+ *
+ * <p><b>None of this is published API, and compatibility can be broken anytime!</b>
+ * Use this only at your own risk.
+ *
+ * @apiNote Internal API
  */
 @InternalApi
 public final class InternalApiBridge {
 
-    private InternalApiBridge() {
-        
-    }
+    private InternalApiBridge() {}
 
     public static void setScope(PLSQLNode node, Scope decl) {
         ((AbstractPLSQLNode) node).setScope(decl);
diff --git a/pmd-visualforce/src/main/java/net/sourceforge/pmd/lang/vf/ast/InternalApiBridge.java b/pmd-visualforce/src/main/java/net/sourceforge/pmd/lang/vf/ast/InternalApiBridge.java
index 5c43ff9dba..4f14298af3 100644
--- a/pmd-visualforce/src/main/java/net/sourceforge/pmd/lang/vf/ast/InternalApiBridge.java
+++ b/pmd-visualforce/src/main/java/net/sourceforge/pmd/lang/vf/ast/InternalApiBridge.java
@@ -8,14 +8,19 @@ import net.sourceforge.pmd.annotation.InternalApi;
 import net.sourceforge.pmd.lang.vf.DataType;
 
 /**
- * This is internal API, and can be changed at any time.
+ * Internal API.
+ *
+ * <p>Acts as a bridge between outer parts of PMD and the restricted access
+ * internal API of this package.
+ *
+ * <p><b>None of this is published API, and compatibility can be broken anytime!</b>
+ * Use this only at your own risk.
+ *
+ * @apiNote Internal API
  */
 @InternalApi
 public final class InternalApiBridge {
-
-    private InternalApiBridge() {
-        // utility class
-    }
+    private InternalApiBridge() {}
 
     public static void setDataType(VfTypedNode node, DataType dataType) {
         ((AbstractVFDataNode) node).setDataType(dataType);