From 600ff541873968b6eca811d7cef9e7535604ef77 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Cl=C3=A9ment=20Fournier?= <clement.fournier76@gmail.com>
Date: Tue, 27 Mar 2018 14:09:36 +0200
Subject: [PATCH] Update rule documentation and changelog

---
 docs/pages/release_notes.md                   | 22 +++++++++++++++++++
 .../resources/category/java/codestyle.xml     | 22 +++++++++++++++++--
 2 files changed, 42 insertions(+), 2 deletions(-)

diff --git a/docs/pages/release_notes.md b/docs/pages/release_notes.md
index 0699c44bce..e19265b605 100644
--- a/docs/pages/release_notes.md
+++ b/docs/pages/release_notes.md
@@ -13,14 +13,36 @@ This is a minor release.
 ### Table Of Contents
 
 * [New and noteworthy](#new-and-noteworthy)
+  * [Naming rules enhancements](#naming-rules-enhancements)
 * [Fixed Issues](#fixed-issues)
 * [API Changes](#api-changes)
+  * [Deprecated Rules](#deprecated-rules)
 * [External Contributions](#external-contributions)
 
 ### New and noteworthy
 
+
+#### Naming rules enhancements
+
+ * [`ClassNamingConventions`](pmd_rules_java_codestyle.html#classnamingconventions)
+  has been enhanced to allow granular configuration of naming
+  conventions for different kinds of type declarations (eg enum or abstract
+  class). Each kind of declaration can use its own naming convention
+  using a regex property. See the rule's documentation for more info about
+  configuration and default conventions.
+
+
 ### Fixed Issues
 
 ### API Changes
 
+#### Deprecated Rules
+
+  * The Java rule `AbstractNaming` (category `codestyle`) is deprecated
+  in favour of [`ClassNamingConventions`](pmd_rules_java_codestyle.html#classnamingconventions).
+  See [Naming rules enhancements](#naming-rules-enhancements).
+
+
+
+
 ### External Contributions
diff --git a/pmd-java/src/main/resources/category/java/codestyle.xml b/pmd-java/src/main/resources/category/java/codestyle.xml
index cdafc4429f..3bcdb4c4f2 100644
--- a/pmd-java/src/main/resources/category/java/codestyle.xml
+++ b/pmd-java/src/main/resources/category/java/codestyle.xml
@@ -12,6 +12,7 @@ Rules which enforce a specific coding style.
     <rule name="AbstractNaming"
           language="java"
           since="1.4"
+          deprecated="true"
           message="Abstract classes should be named 'AbstractXXX'"
           class="net.sourceforge.pmd.lang.rule.XPathRule"
           externalInfoUrl="${pmd.website.baseurl}/pmd_rules_java_codestyle.html#abstractnaming">
@@ -374,12 +375,29 @@ public class Foo extends Bar{
           class="net.sourceforge.pmd.lang.java.rule.codestyle.ClassNamingConventionsRule"
           externalInfoUrl="${pmd.website.baseurl}/pmd_rules_java_codestyle.html#classnamingconventions">
         <description>
-Class names should always begin with an upper case character.
+            Configurable naming conventions for type declarations. This rule reports
+            type declarations which do not match the regex that applies to their
+            specific kind (e.g. enum or interface). Each regex can be configured through
+            properties.
+
+            By default this rule uses the standard Java naming convention (Pascal case),
+            and reports utility class names not ending with 'Util'.
         </description>
         <priority>1</priority>
         <example>
 <![CDATA[
-public class Foo {}
+// This is Pascal case, the recommended naming convention in Java
+// Note that the default values of this rule don't allow numbers,
+// underscores, or accented characters in type names
+public class FooBar {}
+
+// You may want abstract classes to be named 'AbstractXXX',
+// in which case you can customize the regex for abstract
+// classes to 'Abstract[A-Z]\w+'
+public abstract class Thing {}
+
+// This class doesn't respect the convention, and will be flagged
+public class Éléphant {}
 ]]>
         </example>
     </rule>