Document ThrowSpecificity and CatchSpecificity edge cases

baseline-error-prone/src/main/java/com/palantir/baseline/errorprone/CatchSpecificity.java

@@ -60,7 +60,13 @@
         summary = "Prefer more specific error types than Exception and Throwable. When methods are updated to throw "
                 + "new checked exceptions they expect callers to handle failure types explicitly. Catching broad "
                 + "types defeats the type system. By catching the most specific types possible we leverage existing "
-                + "compiler functionality to detect unreachable code.")
+                + "compiler functionality to detect unreachable code.\n"
+                + "Note: Checked exceptions are only validated by the compiler and can be thrown by non-standard "
+                + "bytecode at runtime, for example when java code calls into groovy or scala generated bytecode "
+                + "a checked exception can be thrown despite not being declared. In these scenarios we recommend "
+                + "suppressing this check using @SuppressWarnings(\"CatchSpecificity\") and a comment describing "
+                + "the reason. Remaining instances can be automatically fixed using "
+                + "./gradlew compileJava -PerrorProneApply=CatchSpecificity")
 public final class CatchSpecificity extends BugChecker implements BugChecker.TryTreeMatcher {
 
     // Maximum of three checked exception types to avoid unreadable long catch statements.

baseline-error-prone/src/main/java/com/palantir/baseline/errorprone/ThrowSpecificity.java

@@ -47,7 +47,13 @@
         summary = "Prefer to declare more specific throws types than Exception and Throwable. When methods are "
                 + "updated to throw new checked exceptions they expect callers to handle failure types explicitly. "
                 + "Throwing broad types defeats the type system. By throwing the most specific types possible we "
-                + "leverage existing compiler functionality to detect unreachable code.")
+                + "leverage existing compiler functionality to detect unreachable code.\n"
+                + "Note: Checked exceptions are only validated by the compiler and can be thrown by non-standard "
+                + "bytecode at runtime, for example when java code calls into groovy or scala generated bytecode "
+                + "a checked exception can be thrown despite not being declared. In these scenarios we recommend "
+                + "suppressing this check using @SuppressWarnings(\"ThrowSpecificity\") and a comment describing "
+                + "the reason. Remaining instances can be automatically fixed using "
+                + "./gradlew compileJava -PerrorProneApply=ThrowSpecificity")
 public final class ThrowSpecificity extends BugChecker implements BugChecker.MethodTreeMatcher {
 
     // Maximum of three checked exception types to avoid unreadable long catch statements.

changelog/@unreleased/pr-1118.v2.yml

@@ -0,0 +1,5 @@
+type: improvement
+improvement:
+  description: Document ThrowSpecificity and CatchSpecificity edge cases
+  links:
+  - https://github.com/palantir/gradle-baseline/pull/1118