Modify S1874: Migrate to LayC (#3241)

rules/S1874/cfamily/rule.adoc

@@ -1,45 +1,26 @@
 == Why is this an issue?
 
-Code annotated as deprecated should not be used since it will be removed sooner or later.
-
-=== Noncompliant code example
+include::../description.adoc[]
 
 [source,cpp]
 ----
 // C++14 attribute
-[[deprecated]]
-void fun();
+[[deprecated("Use newFunction instead.")]]
+void oldFunction();
 
 // GNU attribute
-__attribute__((deprecated))
-void fun();
+__attribute__((deprecated("Use newFunction instead.")))
+void oldFunction();
 
 // Microsoft attribute
-__declspec(deprecated)
-void fun();
+__declspec(deprecated("Use newFunction instead."))
+void oldFunction();
+
+void newFunction();
 
 void example() {
-  fun(); // Noncompliant
+  oldFunction(); // Noncompliant
 }
 ----
 
-== Resources
-
-* https://cwe.mitre.org/data/definitions/477[MITRE, CWE-477] - Use of Obsolete Functions
-* https://wiki.sei.cmu.edu/confluence/x/6TdGBQ[CERT, MET02-J.] - Do not use deprecated or obsolete classes or methods
-
-ifdef::env-github,rspecator-view[]
-
-'''
-== Implementation Specification
-(visible only on this page)
-
-include::../message.adoc[]
-
-'''
-== Comments And Links
-(visible only on this page)
-
-include::../comments-and-links.adoc[]
-
-endif::env-github,rspecator-view[]
+include::../see.adoc[]

rules/S1874/description.adoc

@@ -1 +1,7 @@
-Once deprecated, classes, and interfaces, and their members should be avoided, rather than used, inherited or extended. Deprecation is a warning that the class or interface has been superseded, and will eventually be removed. The deprecation period allows you to make a smooth transition away from the aging, soon-to-be-retired technology.
+Code is sometimes annotated as deprecated by developers maintaining libraries or APIs to indicate that the method, class, or other programming element is no longer recommended for use. This is typically due to the introduction of a newer or more effective alternative. For example, when a better solution has been identified, or when the existing code presents potential errors or security risks.
+
+Deprecation is a good practice because it helps to phase out obsolete code in a controlled manner, without breaking existing software that may still depend on it. It is a way to warn other developers not to use the deprecated element in new code, and to replace it in existing code when possible. 
+
+Deprecated classes, interfaces, and their members should not be used, inherited or extended because they will eventually be removed. The deprecation period allows you to make a smooth transition away from the aging, soon-to-be-retired technology.
+
+Check the documentation or the deprecation message to understand why the code was deprecated and what the recommended alternative is.

rules/S1874/java/rule.adoc

@@ -2,25 +2,34 @@
 
 include::../description.adoc[]
 
-include::../noncompliant.adoc[]
-
-== Resources
-
-* https://cwe.mitre.org/data/definitions/477[MITRE, CWE-477] - Use of Obsolete Functions
-* https://wiki.sei.cmu.edu/confluence/x/6TdGBQ[CERT, MET02-J.] - Do not use deprecated or obsolete classes or methods
-
-ifdef::env-github,rspecator-view[]
-
-'''
-== Implementation Specification
-(visible only on this page)
-
-include::../message.adoc[]
-
-'''
-== Comments And Links
-(visible only on this page)
-
-include::../comments-and-links.adoc[]
-
-endif::env-github,rspecator-view[]
+[source,java]
+----
+/**
+ * @deprecated  As of release 1.3, replaced by {@link #Foo}
+ */
+@Deprecated
+public class Fum { ... }
+
+public class Foo {
+  /**
+   * @deprecated  As of release 1.7, replaced by {@link #newMethod()}
+   */
+  @Deprecated
+  public void oldMethod() { ... }
+
+  public void newMethod() { ... }
+}
+
+public class Bar extends Foo {
+  public void oldMethod() { ... } // Noncompliant; don't override a deprecated method
+}
+
+public class Baz extends Fum {  // Noncompliant; Fum is deprecated
+  public void myMethod() {
+    Foo foo = new Foo();
+    foo.oldMethod();  // Noncompliant; oldMethod method is deprecated
+  }
+}
+----
+
+include::../see.adoc[]

rules/S1874/javascript/rule.adoc

@@ -2,34 +2,20 @@
 
 include::../description.adoc[]
 
-=== Noncompliant code example
-
 [source,javascript]
 ----
-export interface LanguageService {
-  /**
-  * @deprecated Use getEncodedSyntacticClassifications instead.
-  */
-  getSyntacticClassifications(fileName: string, span: TextSpan): ClassifiedSpan[];
+/**
+ * @deprecated Use newFunction instead.
+ */
+function oldFunction() {
+  console.log("This is the old function.");
 }
 
-const syntacticClassifications = getLanguageService().getSyntacticClassifications(file, span); // Noncompliant
+function newFunction() {
+  console.log("This is the new function.");
+}
+oldFunction(); // Noncompliant: "oldFunction is deprecated"
 ----
 
-include::../see.adoc[]
-
-ifdef::env-github,rspecator-view[]
-
-'''
-== Implementation Specification
-(visible only on this page)
 
-include::../message.adoc[]
-
-'''
-== Comments And Links
-(visible only on this page)
-
-include::../comments-and-links.adoc[]
-
-endif::env-github,rspecator-view[]
+include::../see.adoc[]

rules/S1874/kotlin/rule.adoc

@@ -1,22 +1,19 @@
 == Why is this an issue?
 
-Code annotated as deprecated should not be used since it will be removed sooner or later.
-
-=== Noncompliant code example
+include::../description.adoc[]
 
 [source,kotlin]
 ----
-@Deprecated("")
-interface Old
-
-class Example : Old // Noncompliant
-----
-ifdef::env-github,rspecator-view[]
+@Deprecated("This function is deprecated, use newFunction instead", ReplaceWith("newFunction()"))
+fun oldFunction() {
+    println("This is the old function.")
+}
 
-'''
-== Implementation Specification
-(visible only on this page)
+fun newFunction() {
+    println("This is the new function.")
+}
 
-include::../message.adoc[]
+oldFunction() // Noncompliant: "oldFunction is deprecated"
+----
 
-endif::env-github,rspecator-view[]
+include::../see.adoc[]

rules/S1874/see.adoc

@@ -1,3 +1,3 @@
 == Resources
-
+=== Documentation
 * https://cwe.mitre.org/data/definitions/477[MITRE, CWE-477] - Use of Obsolete Functions