SONARJAVA-4499 Update rules metadata (#4392)

* SONARJAVA-4499 Update rules metadata, rename sections

* SONARJAVA-4499 Update rules metadata, deprecated rules

* SONARJAVA-4499 Update rules metadata, "See Also" sections

* SONARJAVA-4499 S2384 description updated to match the implementation

* SONARJAVA-4499 Fix S2755 rule description invalid section

* SONARJAVA-4499 Migrate S3981 rule description to the educational format

Author: alban-auzeill

java-checks/src/main/resources/org/sonar/l10n/java/rules/java/S100.html

@@ -1,14 +1,15 @@
+<h2>Why is this an issue?</h2>
 <p>Shared naming conventions allow teams to collaborate efficiently. This rule checks that all method names match a provided regular expression.</p>
-<h2>Noncompliant Code Example</h2>
+<h3>Noncompliant code example</h3>
 <p>With default provided regular expression <code>^[a-z][a-zA-Z0-9]*$</code>:</p>
 <pre>
 public int DoSomething(){...}
 </pre>
-<h2>Compliant Solution</h2>
+<h3>Compliant solution</h3>
 <pre>
 public int doSomething(){...}
 </pre>
-<h2>Exceptions</h2>
+<h3>Exceptions</h3>
 <p>Overriding methods are excluded.</p>
 <pre>
 @Override

java-checks/src/main/resources/org/sonar/l10n/java/rules/java/S101.html

@@ -1,11 +1,12 @@
+<h2>Why is this an issue?</h2>
 <p>Shared coding conventions allow teams to collaborate effectively. This rule allows to check that all class names match a provided regular
 expression.</p>
-<h2>Noncompliant Code Example</h2>
+<h3>Noncompliant code example</h3>
 <p>With default provided regular expression <code>^[A-Z][a-zA-Z0-9]*$</code>:</p>
 <pre>
 class my_class {...}
 </pre>
-<h2>Compliant Solution</h2>
+<h3>Compliant solution</h3>
 <pre>
 class MyClass {...}
 </pre>

java-checks/src/main/resources/org/sonar/l10n/java/rules/java/S103.html

@@ -1,2 +1,3 @@
+<h2>Why is this an issue?</h2>
 <p>Having to scroll horizontally makes it harder to get a quick overview and understanding of any piece of code.</p>
 

java-checks/src/main/resources/org/sonar/l10n/java/rules/java/S104.html

@@ -1,3 +1,4 @@
+<h2>Why is this an issue?</h2>
 <p>A source file that grows too much tends to aggregate too many responsibilities and inevitably becomes harder to understand and therefore to
 maintain. Above a specific threshold, it is strongly advised to refactor it into smaller pieces of code which focus on well defined tasks. Those
 smaller files will not only be easier to understand but also probably easier to test.</p>

java-checks/src/main/resources/org/sonar/l10n/java/rules/java/S105.html

@@ -1,3 +1,4 @@
+<h2>Why is this an issue?</h2>
 <p>Developers should not need to configure the tab width of their text editors in order to be able to read source code.</p>
 <p>So the use of the tabulation character must be banned.</p>
 

java-checks/src/main/resources/org/sonar/l10n/java/rules/java/S106.html

@@ -1,3 +1,4 @@
+<h2>Why is this an issue?</h2>
 <p>When logging a message there are several important requirements which must be fulfilled:</p>
 <ul>
   <li> The user must be able to easily retrieve the logs </li>
@@ -7,15 +8,15 @@
 </ul>
 <p>If a program directly writes to the standard outputs, there is absolutely no way to comply with those requirements. That’s why defining and using a
 dedicated logger is highly recommended.</p>
-<h2>Noncompliant Code Example</h2>
+<h3>Noncompliant code example</h3>
 <pre>
 System.out.println("My Message");  // Noncompliant
 </pre>
-<h2>Compliant Solution</h2>
+<h3>Compliant solution</h3>
 <pre>
 logger.log("My Message");
 </pre>
-<h2>See</h2>
+<h2>Resources</h2>
 <ul>
   <li> <a href="https://owasp.org/Top10/A09_2021-Security_Logging_and_Monitoring_Failures/">OWASP Top 10 2021 Category A9</a> - Security Logging and
   Monitoring Failures </li>

java-checks/src/main/resources/org/sonar/l10n/java/rules/java/S1065.html

@@ -1,6 +1,7 @@
+<h2>Why is this an issue?</h2>
 <p>If a label is declared but not used in the program, it can be considered as dead code and should therefore be removed.</p>
 <p>This will improve maintainability as developers will not wonder what this label is used for.</p>
-<h2>Noncompliant Code Example</h2>
+<h3>Noncompliant code example</h3>
 <pre>
 void foo() {
   outer: //label is not used.
@@ -9,15 +10,15 @@ <h2>Noncompliant Code Example</h2>
   }
 }
 </pre>
-<h2>Compliant Solution</h2>
+<h3>Compliant solution</h3>
 <pre>
 void foo() {
   for(int i = 0; i&lt;10; i++) {
     break;
   }
 }
 </pre>
-<h2>See</h2>
+<h2>Resources</h2>
 <ul>
   <li> <a href="https://wiki.sei.cmu.edu/confluence/x/5dUxBQ">CERT, MSC12-C.</a> - Detect and remove code that has no effect or is never executed
   </li>

java-checks/src/main/resources/org/sonar/l10n/java/rules/java/S1066.html

@@ -1,13 +1,14 @@
+<h2>Why is this an issue?</h2>
 <p>Merging collapsible <code>if</code> statements increases the code’s readability.</p>
-<h2>Noncompliant Code Example</h2>
+<h3>Noncompliant code example</h3>
 <pre>
 if (file != null) {
   if (file.isFile() || file.isDirectory()) {
     /* ... */
   }
 }
 </pre>
-<h2>Compliant Solution</h2>
+<h3>Compliant solution</h3>
 <pre>
 if (file != null &amp;&amp; isFileOrDirectory(file)) {
   /* ... */

java-checks/src/main/resources/org/sonar/l10n/java/rules/java/S1067.html

@@ -1,16 +1,17 @@
+<h2>Why is this an issue?</h2>
 <p>The complexity of an expression is defined by the number of <code>&amp;&amp;</code>, <code>||</code> and <code>condition ? ifTrue : ifFalse</code>
 operators it contains.</p>
 <p>A single expression’s complexity should not become too high to keep the code readable.</p>
-<h2>Noncompliant Code Example</h2>
+<h3>Noncompliant code example</h3>
 <p>With the default threshold value of 3:</p>
 <pre>
 if (((condition1 &amp;&amp; condition2) || (condition3 &amp;&amp; condition4)) &amp;&amp; condition5) { ... }
 </pre>
-<h2>Compliant Solution</h2>
+<h3>Compliant solution</h3>
 <pre>
 if ( (myFirstCondition() || mySecondCondition()) &amp;&amp; myLastCondition()) { ... }
 </pre>
-<h2>Exceptions</h2>
+<h3>Exceptions</h3>
 <p>No issue is reported inside <code>equals</code> methods, because it is common to compare all the fields of a class for equality inside this kind of
 method.</p>
 

java-checks/src/main/resources/org/sonar/l10n/java/rules/java/S1068.html

@@ -1,8 +1,9 @@
+<h2>Why is this an issue?</h2>
 <p>If a <code>private</code> field is declared but not used in the program, it can be considered dead code and should therefore be removed. This will
 improve maintainability because developers will not wonder what the variable is used for.</p>
 <p>Note that this rule does not take reflection into account, which means that issues will be raised on <code>private</code> fields that are only
 accessed using the reflection API.</p>
-<h2>Noncompliant Code Example</h2>
+<h3>Noncompliant code example</h3>
 <pre>
 public class MyClass {
   private int foo = 42;
@@ -13,22 +14,19 @@ <h2>Noncompliant Code Example</h2>
 
 }
 </pre>
-<h2>Compliant Solution</h2>
+<h3>Compliant solution</h3>
 <pre>
 public class MyClass {
   public int compute(int a) {
     return a * 42;
   }
 }
 </pre>
-<h2>Exceptions</h2>
+<h3>Exceptions</h3>
 <p>The rule admits 3 exceptions:</p>
 <ul>
   <li> Serialization id fields </li>
-  <li> Annotated fields </li>
-  <li> Fields from classes with native methods </li>
 </ul>
-<h3>Serialization id fields</h3>
 <p>The Java serialization runtime associates with each serializable class a version number, called <code>serialVersionUID</code>, which is used during
 deserialization to verify that the sender and receiver of a serialized object have loaded classes for that object that are compatible with respect to
 serialization.</p>
@@ -39,15 +37,19 @@ <h3>Serialization id fields</h3>
   private static final long serialVersionUID = 42L;
 }
 </pre>
-<h3>Annotated fields</h3>
+<ul>
+  <li> Annotated fields </li>
+</ul>
 <p>The unused field in this class will not be reported by the rule as it is annotated.</p>
 <pre>
 public class MyClass {
   @SomeAnnotation
   private int unused;
 }
 </pre>
-<h3>Fields from classes with native methods</h3>
+<ul>
+  <li> Fields from classes with native methods </li>
+</ul>
 <p>The unused field in this class will not be reported by the rule as it might be used by native code.</p>
 <pre>
 public class MyClass {