Java: updated visible-for-testing-abuse meta data and docs.

Author: Napalys

java/ql/src/Violations of Best Practice/Implementation Hiding/VisibleForTestingAbuse.md

@@ -1,10 +1,8 @@
-# J-T-003: Accessing any method, field or class annotated with `@VisibleForTesting` from production code is discouraged
+## Overview
 
 Accessing class members annotated with `@VisibleForTesting` from production code goes against the intention of the annotation and may indicate programmer error.
 
-## Overview
-
-The `@VisibleForTesting` serves to increase visibility of methods, fields or classes for the purposes of testing. Accessing methods, fields or classes that are annotated with `@VisibleForTesting` in production code (not test code) abuses the intention of the annotation.
+The `@VisibleForTesting` annotation serves to increase visibility of methods, fields or classes for the purposes of testing. Accessing these annotated elements in production code (not test code) abuses the intention of the annotation.
 
 ## Recommendation
 
@@ -14,15 +12,14 @@ Only access methods, fields or classes annotated with `@VisibleForTesting` from
 
 ```java
 public class Annotated {
-@VisibleForTesting static int f(){}
+    @VisibleForTesting static int f() { return 42; }
 }
 
 /* src/test/java/Test.java */
 int i = Annotated.f(); // COMPLIANT
 
 /* src/main/Source.java */
- int i = Annotated.f(); // NON_COMPLIANT
-
+int i = Annotated.f(); // NON_COMPLIANT
 ```
 
 ## Implementation notes
@@ -31,9 +28,9 @@ This rule alerts on any implementation of the annotation `VisibleForTesting`, re
 
 The rule also uses the following logic to determine what an abuse of the annotation is:
 
-  1) If public or protected member/type is annotated with `VisibleForTesting`, it's assumed that package-private access is enough for production code. Therefore the rule alerts when a public or protected member/type annotated with `VisibleForTesting` is used outside of its declaring package.
-  2) If package-private member/type is annotated with `VisibleForTesting`, it's assumed that private access is enough for production code. Therefore the rule alerts when a package-private member/type annotated with `VisibleForTesting` is used outside its declaring class.
+  1. If a public or protected member/type is annotated with `@VisibleForTesting`, it's assumed that package-private access is enough for production code. Therefore the rule alerts when a public or protected member/type annotated with `@VisibleForTesting` is used outside of its declaring package.
+  2. If a package-private member/type is annotated with `@VisibleForTesting`, it's assumed that private access is enough for production code. Therefore the rule alerts when a package-private member/type annotated with `@VisibleForTesting` is used outside its declaring class.
 
 ## References
-- Example Specific Implementation of a VisibleForTesting Annotation: [AssertJ VisibleForTesting](https://javadoc.io/doc/org.assertj/assertj-core/latest/org/assertj/core/util/VisibleForTesting.html)
-- Assumptions of what level of access is permittable for each access modifier and the annotation: [JetBrains VisibleForTesting](https://javadoc.io/doc/org.jetbrains/annotations/22.0.0/org/jetbrains/annotations/VisibleForTesting.html)
+- Javadoc: [AssertJ VisibleForTesting](https://javadoc.io/doc/org.assertj/assertj-core/latest/org/assertj/core/util/VisibleForTesting.html).
+- Javadoc: [JetBrains VisibleForTesting](https://javadoc.io/doc/org.jetbrains/annotations/22.0.0/org/jetbrains/annotations/VisibleForTesting.html).

java/ql/src/Violations of Best Practice/Implementation Hiding/VisibleForTestingAbuse.ql

@@ -1,7 +1,7 @@
 /**
  * @id java/visible-for-testing-abuse
- * @name Accessing any method, field or class annotated with `@VisibleForTesting` from production code is discouraged
- * @description Accessing any method, field or class annotated with `@VisibleForTesting` from
+ * @name Use of VisibleForTesting in production code
+ * @description Accessing methods, fields or classes annotated with `@VisibleForTesting` from
  *              production code goes against the intention of the annotation and may indicate
  *              programmer error.
  * @kind problem