Better 'last resort' explanation

Author: chashnikov

common/src/main/java/org/jetbrains/annotations/TestOnly.java

@@ -23,7 +23,10 @@
  * Apart from documentation purposes this annotation is intended to be used by static analysis tools
  * to validate against element contract violations.
  * <p>
- * This annotation should be used only as a last resort.
+ * This annotation means that the annotated element exposes internal data and breaks encapsulation 
+ * of the containing class; the annotation won't prevent its use from production code, developers 
+ * even won't see warnings if their IDE doesn't support the annotation. It's better to provide 
+ * proper API which can be used in production as well as in tests.
  */
 @Documented
 @Retention(RetentionPolicy.CLASS)

common/src/main/java/org/jetbrains/annotations/VisibleForTesting.java

@@ -32,7 +32,10 @@
  *   <li>It's illegal to annotate private member/type as VisibleForTesting.</li>
  * </ul>
  * <p>
- * This annotation should be used only as a last resort.
+ * This annotation means that the annotated element exposes internal data and breaks encapsulation 
+ * of the containing class; the annotation won't prevent its use from production code, developers 
+ * even won't see warnings if their IDE doesn't support the annotation. It's better to provide 
+ * proper API which can be used in production as well as in tests.
  * 
  * @since 20.0.0
  */