Modify rule S6322: Migrate to LaYC format (#3171)

rules/S6322/java/rule.adoc

@@ -1,25 +1,40 @@
+Many modification methods in the collection interfaces are optional.
+Some implementations do not implement those methods and throw a runtime exception (`UnsupportedOperationException`).
+To fix this issue, make sure you call modification methods on a collection implementation that supports them.
+
 == Why is this an issue?
 
-The Java Collections framework defines interfaces such as `java.util.List` or `java.util.Map`. Several implementation classes are provided for each of those interfaces to fill different needs: some of the implementations guarantee a few given performance characteristics, some others ensure a given behavior, for example immutability.
+The Java Collections framework defines interfaces such as `java.util.List` or `java.util.Map`.
+Several implementation classes are provided for each of those interfaces to fill different needs: some of the implementations guarantee a few given performance characteristics, some others ensure a given behavior, for example immutability.
+
+Among the methods defined by the interfaces of the Collections framework, some are declared as "optional": an implementation class may choose to throw an `UnsupportedOperationException` when one of those methods is called.
+For example, `java.util.Collections.emptyList()` returns an implementation of `java.util.List` which is documented as "immutable".
+Calling the `add` method on this object triggers an `UnsupportedOperationException`.
+
+=== What is the potential impact?
 
-Among the methods defined by the interfaces of the Collections framework, some are declared as "optional": an implementation class may choose to throw an `UnsupportedOperationException` when one of those methods is called. For example, `java.util.Collections.emptyList()` returns an implementation of `java.util.List` which is documented as "immutable": calling the `add` method on this object triggers an `UnsupportedOperationException`.
+include::../../../shared_content/layc/exception-impact.adoc[]
 
-When calling one of the "optional" methods, a developer should therefore make sure that the implementation class on which the call is made indeed supports this method.
+== How to fix it
 
-=== Noncompliant code example
+When calling a method labeled as optional, you should make sure that the implementation class on which the call is made indeed supports this method.
 
-[source,java]
+=== Code examples
+
+==== Noncompliant code example
+
+[source,java,diff-id=1,diff-type=noncompliant]
 ----
-List<String> list = Collections.emptyList();
+List<String> list = Collections.emptyList(); // The list implementation returned here is unmodifiable.
 if (someCondition) {
   list.add("hello"); // Noncompliant; throws an UnsupportedOperationException
 }
 return list;
 ----
 
-=== Compliant solution
+==== Compliant solution
 
-[source,java]
+[source,java,diff-id=1,diff-type=compliant]
 ----
 List<String> list = new ArrayList<>();
 if (someCondition) {
@@ -30,7 +45,7 @@ return list;
 
 or
 
-[source,java]
+[source,java,diff-id=1,diff-type=compliant]
 ----
 if (someCondition) {
   return Collections.singletonList("hello");
@@ -40,4 +55,9 @@ return Collections.emptyList();
 
 == Resources
 
-* https://docs.oracle.com/javase/8/docs/technotes/guides/collections/overview.html[Collections Framework Overview] in the Java documentation
+=== Documentation
+
+* https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/doc-files/coll-overview.html[Collections Framework Overview] in the Java documentation
+* https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/List.html[List] in the Java documentation
+* https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/Set.html[Set] in the Java documentation
+* https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/Map.html[Map] in the Java documentation