use tags to include blocks of code

rules/S3457/c-family/compliant.c

@@ -1,6 +1,8 @@
 #include <stdio.h>
 
 int main() {
+    // tag::include[]
     printf("%d %d", 1, 2); // Compliant
     printf("%-f", 1.2); // Compliant
+    // end::include[]
 } 

rules/S3457/c-family/noncompliant.c

@@ -1,6 +1,8 @@
 #include <stdio.h>
 
 int main() {
+    // tag::include[]
     printf("%d", 1, 2); // Noncompliant; the second argument "2" is unused
     printf("%0-f", 1.2); // Noncompliant; flag "0" is ignored because of "-"
+    // end::include[]
 }

rules/S3457/c-family/rule.adoc

@@ -12,12 +12,12 @@ This rule will only work if the format string is provided as a string literal.
 
 == Noncompliant Code Example
 ----
-include::noncompliant.c[lines=4..5]
+include::noncompliant.c[tag=include]
 ----
 
 == Compliant Solution
 ----
-include::compliant.c[lines=4..5]
+include::compliant.c[tag=include]
 ----
 
 == See

rules/S3457/java/compliant.java

@@ -3,29 +3,39 @@
 public class Main
 {
     public void main() {
+        // tag::String.format[]
         String.format("First %s and then %s", "foo", "bar");
         String.format("Display %2$d and then %d", 1, 3);
         String.format("Too many arguments %d %d", 1, 2);
         String.format("First Line%n");
         String.format("Is myObject null ? %b", myObject == null);
         String.format("value is %d", value);
-        String s = "string without arguments"; 
+        String s = "string without arguments";
+        // end::String.format[]
 
+        // tag::MessageFormat[]
         MessageFormat.format("Result {0}.", value);
         MessageFormat.format("Result '{0}'  =  {0}", value);
         MessageFormat.format("Result {0}.", myObject);
+        // end::MessageFormat[]
 
+        // tag::java.util.Logger[]
         java.util.Logger logger;
         logger.log(java.util.logging.Level.SEVERE, "Result {0}.", myObject);
         logger.log(java.util.logging.Level.SEVERE, "Result {0}'", 14);
         logger.log(java.util.logging.Level.SEVERE, exception, () -> "Result " + param);
+        // end::java.util.Logger[]
 
+        // tag::org.slf4j.Logger[]
         org.slf4j.Logger slf4jLog;
         org.slf4j.Marker marker;
         slf4jLog.debug(marker, "message {}");
         slf4jLog.debug(marker, "message {}", 1);
+        // end::org.slf4j.Logger[]
 
+        // tag::org.apache.logging.log4j.Logger[]
         org.apache.logging.log4j.Logger log4jLog;
         log4jLog.debug("message {}", 1);
+        // end::org.apache.logging.log4j.Logger[]
     }
 }

rules/S3457/java/noncompliant.java

@@ -3,6 +3,7 @@
 public class Main
 {
     public void main() {
+        // tag::String.format[]
         String.format("First {0} and then {1}", "foo", "bar");  //Noncompliant. Looks like there is a confusion with the use of {{java.text.MessageFormat}}, parameters "foo" and "bar" will be simply ignored here
         String.format("Display %3$d and then %d", 1, 2, 3);   //Noncompliant; the second argument '2' is unused
         String.format("Too many arguments %d and %d", 1, 2, 3);  //Noncompliant; the third argument '3' is unused
@@ -10,23 +11,32 @@ public class Main
         String.format("Is myObject null ? %b", myObject);   //Noncompliant; when a non-boolean argument is formatted with %b, it prints true for any nonnull value, and false for null. Even if intended, this is misleading. It's better to directly inject the boolean value (myObject == null in this case)
         String.format("value is " + value); // Noncompliant
         String s = String.format("string without arguments"); // Noncompliant
+        // end::String.format[]
 
+        // tag::MessageFormat[]
         MessageFormat.format("Result '{0}'.", value); // Noncompliant; String contains no format specifiers. (quote are discarding format specifiers)
         MessageFormat.format("Result {0}.", value, value);  // Noncompliant; 2nd argument is not used
         MessageFormat.format("Result {0}.", myObject.toString()); // Noncompliant; no need to call toString() on objects
+        // end::MessageFormat[]
 
+        // tag::java.util.Logger[]
         java.util.Logger logger;
         logger.log(java.util.logging.Level.SEVERE, "Result {0}.", myObject.toString()); // Noncompliant; no need to call toString() on objects
         logger.log(java.util.logging.Level.SEVERE, "Result.", new Exception()); // compliant, parameter is an exception
         logger.log(java.util.logging.Level.SEVERE, "Result '{0}'", 14); // Noncompliant - String contains no format specifiers.
         logger.log(java.util.logging.Level.SEVERE, "Result " + param, exception); // Noncompliant; Lambda should be used to differ string concatenation.
+        // end::java.util.Logger[]
 
+        // tag::org.slf4j.Logger[]
         org.slf4j.Logger slf4jLog;
         org.slf4j.Marker marker;
         slf4jLog.debug(marker, "message {}");
         slf4jLog.debug(marker, "message", 1); // Noncompliant - String contains no format specifiers.
+        // end::org.slf4j.Logger[]
 
+        // tag::org.apache.logging.log4j.Logger[]
         org.apache.logging.log4j.Logger log4jLog;
         log4jLog.debug("message", 1); // Noncompliant - String contains no format specifiers.
+        // end::org.apache.logging.log4j.Logger[]
     }
 }

rules/S3457/java/rule.adoc

@@ -6,37 +6,37 @@ Because `printf`-style format strings are interpreted at runtime, rather than va
 
 == Noncompliant Code Example
 ----
-include::noncompliant.java[lines=6..12]
+include::noncompliant.java[tag=String.format]
 ----
 ----
-include::noncompliant.java[lines=14..16]
+include::noncompliant.java[tag=MessageFormat]
 ----
 ----
-include::noncompliant.java[lines=18..22]
+include::noncompliant.java[tag=java.util.Logger]
 ----
 ----
-include::noncompliant.java[lines=24..27]
+include::noncompliant.java[tag=org.slf4j.Logger]
 ----
 ----
-include::noncompliant.java[lines=29..30]
+include::noncompliant.java[tag=org.apache.logging.log4j.Logger]
 ----
 
 == Compliant Solution
 [source,indent=0]
 ----
-include::compliant.java[lines=6..12]
+include::compliant.java[tag=String.format]
 ----
 ----
-include::compliant.java[lines=14..16]
+include::compliant.java[tag=MessageFormat]
 ----
 ----
-include::compliant.java[lines=18..21]
+include::compliant.java[tag=java.util.Logger]
 ----
 ----
-include::compliant.java[lines=23..26]
+include::compliant.java[tag=org.slf4j.Logger]
 ----
 ----
-include::compliant.java[lines=28..29]
+include::compliant.java[tag=org.apache.logging.log4j.Logger]
 ----
 
 == See