Add comments and update release notes

docs/pages/release_notes.md

@@ -18,6 +18,12 @@ This is a {{ site.pmd.release_type }} release.
 
 ### API Changes
 
+#### Deprecated APIs
+
+* Implementations of {% jdoc core::lang.rule.RuleViolationFactory %} in each language module, eg {% jdoc java::lang.java.rule.JavaRuleViolationFactory %}. 
+
+
+
 ### External Contributions
 
 {% endtocmaker %}

pmd-apex/src/main/java/net/sourceforge/pmd/lang/apex/rule/ApexRuleViolationFactory.java

@@ -10,7 +10,11 @@ import net.sourceforge.pmd.RuleViolation;
 import net.sourceforge.pmd.annotation.InternalApi;
 import net.sourceforge.pmd.lang.ast.Node;
 import net.sourceforge.pmd.lang.rule.AbstractRuleViolationFactory;
+import net.sourceforge.pmd.lang.rule.RuleViolationFactory;
 
+/**
+ * @deprecated See {@link RuleViolationFactory}
+ */
 @Deprecated
 @InternalApi
 public final class ApexRuleViolationFactory extends AbstractRuleViolationFactory {

pmd-core/src/main/java/net/sourceforge/pmd/lang/rule/RuleViolationFactory.java

@@ -6,11 +6,16 @@ package net.sourceforge.pmd.lang.rule;
 
 import net.sourceforge.pmd.Rule;
 import net.sourceforge.pmd.RuleContext;
+import net.sourceforge.pmd.lang.LanguageVersionHandler;
 import net.sourceforge.pmd.lang.ast.Node;
 
 /**
  * This class handles of producing a Language specific RuleViolation and adding
  * to a Report.
+ *
+ * <p>Since PMD 6.21.0, implementations of this interface are considered internal
+ * API and hence deprecated. Clients should exclusively use this interface and obtain
+ * instances through {@link LanguageVersionHandler#getRuleViolationFactory()}.
  */
 public interface RuleViolationFactory {
     /**

pmd-java/src/main/java/net/sourceforge/pmd/lang/java/rule/JavaRuleViolationFactory.java

@@ -13,6 +13,9 @@ import net.sourceforge.pmd.lang.java.ast.JavaNode;
 import net.sourceforge.pmd.lang.rule.AbstractRuleViolationFactory;
 import net.sourceforge.pmd.lang.rule.RuleViolationFactory;
 
+/**
+ * @deprecated See {@link RuleViolationFactory}
+ */
 @Deprecated
 @InternalApi
 public final class JavaRuleViolationFactory extends AbstractRuleViolationFactory {

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

@@ -12,7 +12,11 @@ import net.sourceforge.pmd.lang.ast.Node;
 import net.sourceforge.pmd.lang.ecmascript.ast.EcmascriptNode;
 import net.sourceforge.pmd.lang.rule.AbstractRuleViolationFactory;
 import net.sourceforge.pmd.lang.rule.ParametricRuleViolation;
+import net.sourceforge.pmd.lang.rule.RuleViolationFactory;
 
+/**
+ * @deprecated See {@link RuleViolationFactory}
+ */
 @Deprecated
 @InternalApi
 public final class EcmascriptRuleViolationFactory extends AbstractRuleViolationFactory {

pmd-jsp/src/main/java/net/sourceforge/pmd/lang/jsp/rule/JspRuleViolationFactory.java

@@ -14,6 +14,9 @@ import net.sourceforge.pmd.lang.rule.AbstractRuleViolationFactory;
 import net.sourceforge.pmd.lang.rule.ParametricRuleViolation;
 import net.sourceforge.pmd.lang.rule.RuleViolationFactory;
 
+/**
+ * @deprecated See {@link RuleViolationFactory}
+ */
 @Deprecated
 @InternalApi
 public final class JspRuleViolationFactory extends AbstractRuleViolationFactory {

pmd-plsql/src/main/java/net/sourceforge/pmd/lang/plsql/rule/PLSQLRuleViolationFactory.java

@@ -13,6 +13,9 @@ import net.sourceforge.pmd.lang.rule.AbstractRuleViolationFactory;
 import net.sourceforge.pmd.lang.rule.ParametricRuleViolation;
 import net.sourceforge.pmd.lang.rule.RuleViolationFactory;
 
+/**
+ * @deprecated See {@link RuleViolationFactory}
+ */
 @Deprecated
 @InternalApi
 public final class PLSQLRuleViolationFactory extends AbstractRuleViolationFactory {

pmd-scala/src/main/java/net/sourceforge/pmd/lang/scala/rule/ScalaRuleViolationFactory.java

@@ -14,7 +14,7 @@ import net.sourceforge.pmd.lang.rule.ParametricRuleViolation;
 import net.sourceforge.pmd.lang.rule.RuleViolationFactory;
 
 /**
- * A RuleViolationFactory for Scala.
+ * @deprecated See {@link RuleViolationFactory}
  */
 @Deprecated
 @InternalApi

pmd-visualforce/src/main/java/net/sourceforge/pmd/lang/vf/rule/VfRuleViolationFactory.java

@@ -14,6 +14,9 @@ import net.sourceforge.pmd.lang.rule.ParametricRuleViolation;
 import net.sourceforge.pmd.lang.rule.RuleViolationFactory;
 import net.sourceforge.pmd.lang.vf.ast.VfNode;
 
+/**
+ * @deprecated See {@link RuleViolationFactory}
+ */
 @Deprecated
 @InternalApi
 public final class VfRuleViolationFactory extends AbstractRuleViolationFactory {

pmd-vm/src/main/java/net/sourceforge/pmd/lang/vm/rule/VmRuleViolationFactory.java

@@ -14,6 +14,9 @@ import net.sourceforge.pmd.lang.rule.ParametricRuleViolation;
 import net.sourceforge.pmd.lang.rule.RuleViolationFactory;
 import net.sourceforge.pmd.lang.vm.ast.AbstractVmNode;
 
+/**
+ * @deprecated See {@link RuleViolationFactory}
+ */
 @Deprecated
 @InternalApi
 public final class VmRuleViolationFactory extends AbstractRuleViolationFactory {

pmd-xml/src/main/java/net/sourceforge/pmd/lang/xml/rule/XmlRuleViolationFactory.java

@@ -14,6 +14,9 @@ import net.sourceforge.pmd.lang.rule.ParametricRuleViolation;
 import net.sourceforge.pmd.lang.rule.RuleViolationFactory;
 import net.sourceforge.pmd.lang.xml.ast.XmlNode;
 
+/**
+ * @deprecated See {@link RuleViolationFactory}
+ */
 @Deprecated
 @InternalApi
 public final class XmlRuleViolationFactory extends AbstractRuleViolationFactory {