From 157cac92180ea7935b87963551dfbf8aaf6d1fac Mon Sep 17 00:00:00 2001
From: Andreas Dangel <andreas.dangel@pmd-code.org>
Date: Thu, 27 Apr 2023 20:37:54 +0200
Subject: [PATCH] [doc] CommentRequired - doc changed behavior

---
 docs/pages/release_notes.md                   |  6 ++++
 docs/pages/release_notes_pmd7.md              |  6 ++++
 .../documentation/xml/CommentRequired.xml     | 29 +++++++++++++++++++
 3 files changed, 41 insertions(+)

diff --git a/docs/pages/release_notes.md b/docs/pages/release_notes.md
index 2257018d08..8f0ef94360 100644
--- a/docs/pages/release_notes.md
+++ b/docs/pages/release_notes.md
@@ -278,6 +278,12 @@ Contributors: [Lucas Soncini](https://github.com/lsoncini) (@lsoncini),
 * {% rule java/documentation/CommentContent %}: The properties `caseSensitive` and `disallowedTerms` are removed. The
   new property `fobiddenRegex` can be used now to define the disallowed terms with a single regular
   expression.
+* {% rule java/documentation/CommentRequired %}:
+  * Overridden methods are now detected even without the `@Override`
+    annotation. This is relevant for the property `methodWithOverrideCommentRequirement`.
+    See also [pull request #3757](https://github.com/pmd/pmd/pull/3757).
+  * Elements in annotation types are now detected as well. This might lead to an increased number of violations
+    for missing public method comments.
 * {% rule java/documentation/CommentSize %}: When determining the line-length of a comment, the leading comment
   prefix markers (e.g. `*` or `//`) are ignored and don't add up to the line-length.
   See also [pull request #4369](https://github.com/pmd/pmd/pull/4369).
diff --git a/docs/pages/release_notes_pmd7.md b/docs/pages/release_notes_pmd7.md
index f14444186a..7449e0d131 100644
--- a/docs/pages/release_notes_pmd7.md
+++ b/docs/pages/release_notes_pmd7.md
@@ -613,6 +613,12 @@ Related issue: [[core] Explicitly name all language versions (#4120)](https://gi
 * {% rule java/documentation/CommentContent %}: The properties `caseSensitive` and `disallowedTerms` are removed. The
   new property `fobiddenRegex` can be used now to define the disallowed terms with a single regular
   expression.
+* {% rule java/documentation/CommentRequired %}:
+  * Overridden methods are now detected even without the `@Override`
+    annotation. This is relevant for the property `methodWithOverrideCommentRequirement`.
+    See also [pull request #3757](https://github.com/pmd/pmd/pull/3757).
+  * Elements in annotation types are now detected as well. This might lead to an increased number of violations
+    for missing public method comments.
 * {% rule java/documentation/CommentSize %}: When determining the line-length of a comment, the leading comment
   prefix markers (e.g. `*` or `//`) are ignored and don't add up to the line-length.
   See also [pull request #4369](https://github.com/pmd/pmd/pull/4369).
diff --git a/pmd-java/src/test/resources/net/sourceforge/pmd/lang/java/rule/documentation/xml/CommentRequired.xml b/pmd-java/src/test/resources/net/sourceforge/pmd/lang/java/rule/documentation/xml/CommentRequired.xml
index 9e28b92f13..b8328ba236 100755
--- a/pmd-java/src/test/resources/net/sourceforge/pmd/lang/java/rule/documentation/xml/CommentRequired.xml
+++ b/pmd-java/src/test/resources/net/sourceforge/pmd/lang/java/rule/documentation/xml/CommentRequired.xml
@@ -532,4 +532,33 @@ public class CommentRequirement {}
 public class CommentRequirement {}
         ]]></code>
     </test-code>
+
+    <test-code>
+        <description>Method overridden without @Override (#3123)</description>
+        <rule-property name="methodWithOverrideCommentRequirement">Required</rule-property>
+        <expected-problems>1</expected-problems>
+        <expected-linenumbers>4</expected-linenumbers>
+        <code><![CDATA[
+/** Comment */
+public class CommentRequirement {
+    //no @Override annotation
+    public String toString() { // comment required
+        return "";
+    }
+}
+]]></code>
+    </test-code>
+
+    <test-code>
+        <description>Methods inside annotations (#3123)</description>
+        <expected-problems>2</expected-problems>
+        <expected-linenumbers>3,4</expected-linenumbers>
+        <code><![CDATA[
+/** Comment */
+@interface MyAnnotation1 {
+    String name(); // comment required
+    int version(); // comment required
+}
+]]></code>
+    </test-code>
 </test-data>