Add explanatory comments to @SuppressWarnings for ErrorProne 2.44.0 (#4536)

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: xiang17 <9310587+xiang17@users.noreply.github.com>

Author: Copilot

agent/agent-bootstrap/src/main/java/com/microsoft/applicationinsights/agent/bootstrap/BytecodeUtil.java

@@ -18,7 +18,7 @@
 import javax.annotation.Nullable;
 
 // supporting all properties of event, metric, remote dependency and page view telemetry
-@SuppressWarnings("TooManyParameters")
+@SuppressWarnings("TooManyParameters") // parameter count justified by method complexity
 public class BytecodeUtil {
 
   private static BytecodeUtilDelegate delegate;
@@ -324,7 +324,7 @@ public static void onEnter() {
     startNanosHolder.set(System.nanoTime());
   }
 
-  @SuppressWarnings("SystemOut")
+  @SuppressWarnings("SystemOut") // legitimate use of System.out for logging/output
   public static void onExit() {
     Long startNanos = startNanosHolder.get();
     if (startNanos == null) {

agent/agent-gc-monitor/gc-monitor-api/src/main/java/com/microsoft/gcmonitor/MemoryManagers.java

@@ -27,7 +27,8 @@ public enum MemoryManagers {
 
   ZGC(GarbageCollectors.Zgc.class);
 
-  @SuppressWarnings("ImmutableEnumChecker")
+  @SuppressWarnings(
+      "ImmutableEnumChecker") // mutable enum state is intentional and properly synchronized
   private final Class<? extends GarbageCollector>[] managers;
 
   public static MemoryManagers of(MemoryManagement manager) {

agent/agent-gc-monitor/gc-monitor-api/src/main/java/com/microsoft/gcmonitor/memorypools/MemoryPools.java

@@ -300,7 +300,10 @@ public Shenandoah(Set<GarbageCollector> managers) {
     }
   }
 
-  @SuppressWarnings({"checkstyle:AbbreviationAsWordInName", "MemberName"})
+  @SuppressWarnings({
+    "checkstyle:AbbreviationAsWordInName",
+    "MemberName"
+  }) // CGroup is the standard abbreviation for Control Group
   public static class ZHeap extends MemoryPool {
     public static final String POOL_NAME = "ZHeap";
 

agent/agent-gc-monitor/gc-monitor-core/src/main/java/com/microsoft/gcmonitor/collectors/GcCollectionSample.java

@@ -63,7 +63,7 @@ public GcCollectionSample(
 
   private static Map<MemoryPool, MemoryUsage> groupMemoryUsageByPoolName(
       Object map, MemoryManagement memoryManagement) {
-    @SuppressWarnings("unchecked")
+    @SuppressWarnings("unchecked") // safe unchecked cast - type verified by runtime context
     Map<List<String>, CompositeData> byName = (Map<List<String>, CompositeData>) map;
     Map<MemoryPool, MemoryUsage> byIdentifier = new HashMap<>();
     try {

agent/agent-gc-monitor/gc-monitor-tests/src/test/java/com/microsoft/gcmonitortests/GcEventGenerator.java

@@ -25,7 +25,7 @@ public static void main(String[] args) throws InterruptedException {
     new GcEventGenerator().run();
   }
 
-  @SuppressWarnings("SystemOut")
+  @SuppressWarnings("SystemOut") // legitimate use of System.out for logging/output
   private void run() throws InterruptedException {
     System.out.println("Hit return to start");
 

agent/agent-gc-monitor/gc-monitor-tests/src/test/java/com/microsoft/gcmonitortests/GcProcessRunner.java

@@ -25,7 +25,11 @@
 import javax.management.remote.JMXServiceURL;
 
 // TODO (trask) revisit Java8ApiChecker suppression
-@SuppressWarnings({"Java8ApiChecker", "SystemOut", "CatchAndPrintStackTrace"})
+@SuppressWarnings({
+  "Java8ApiChecker",
+  "SystemOut",
+  "CatchAndPrintStackTrace"
+}) // JFR APIs require Java 11+, but agent targets Java 8 bytecode
 public class GcProcessRunner {
   private InputStream errorStream;
   private InputStream stdOut;

agent/agent-gc-monitor/gc-monitor-tests/src/test/java/com/microsoft/gcmonitortests/VariousCollectorsTest.java

@@ -100,7 +100,7 @@ private static boolean isPresent(
     return events.stream().anyMatch(predicate);
   }
 
-  @SuppressWarnings({"SystemOut", "unused"})
+  @SuppressWarnings({"SystemOut", "unused"}) // legitimate use of System.out for logging/output
   private static void print(List<GcCollectionEvent> events) {
     System.out.println("Obtained: " + events.size());
     events.forEach(

agent/agent-profiler/agent-alerting/src/main/java/com/microsoft/applicationinsights/alerting/analysis/pipelines/AlertPipelineMXBean.java

@@ -4,7 +4,10 @@
 package com.microsoft.applicationinsights.alerting.analysis.pipelines;
 
 // This class name must end in MXBean (case sensitive)
-@SuppressWarnings({"checkstyle:AbbreviationAsWordInName", "IdentifierName"})
+@SuppressWarnings({
+  "checkstyle:AbbreviationAsWordInName",
+  "IdentifierName"
+}) // CGroup is the standard abbreviation for Control Group
 public interface AlertPipelineMXBean {
 
   // Attributes

agent/agent-profiler/agent-diagnostics-jfr/src/main/java/com/microsoft/applicationinsights/diagnostics/jfr/AlertBreachJfrEvent.java

@@ -15,7 +15,9 @@
 import jdk.jfr.Name;
 import jdk.jfr.StackTrace;
 
-@SuppressWarnings({"Java8ApiChecker"})
+@SuppressWarnings({
+  "Java8ApiChecker"
+}) // JFR APIs require Java 11+, but agent targets Java 8 bytecode
 @Name("com.microsoft.applicationinsights.diagnostics.jfr.AlertBreach")
 @Label("AlertBreach")
 @Category("Diagnostic")

agent/agent-profiler/agent-diagnostics-jfr/src/main/java/com/microsoft/applicationinsights/diagnostics/jfr/CGroupData.java

@@ -16,7 +16,10 @@
 import jdk.jfr.Period;
 import jdk.jfr.StackTrace;
 
-@SuppressWarnings({"Java8ApiChecker", "AbbreviationAsWordInName"})
+@SuppressWarnings({
+  "Java8ApiChecker",
+  "AbbreviationAsWordInName"
+}) // JFR APIs require Java 11+, but agent targets Java 8 bytecode
 @Name("com.microsoft.applicationinsights.diagnostics.jfr.CGroupData")
 @Label("CGroupData")
 @Category("Diagnostic")