From 70582f9ede82a212a007e225bcaa3696b08654ba Mon Sep 17 00:00:00 2001
From: Artem Pianykh <arr@fb.com>
Date: Tue, 25 Feb 2020 03:39:59 -0800
Subject: [PATCH] [annotations] Fix annotation comments that cause javadoc
 target to fail

Summary:
When trying to add annotations to code examples, Javadoc gets confused about `@` sign and there's no good way to fix it so it's both OK to read as a comment in the editor and as a Javadoc HTML, no matter what combination of <code>/<pre>/{code} or escaping you use.

Here we prioritise ability to read the code comment from the editor and therefore the comments are detached from annotations.

Facebook

Reviewed By: mityal

Differential Revision: D20093801

fbshipit-source-id: 25867c27a
---
 .../com/facebook/infer/annotation/Assertions.java  | 10 +++++-----
 .../com/facebook/infer/annotation/FalseOnNull.java | 10 +++++-----
 .../com/facebook/infer/annotation/Initializer.java | 10 +++++-----
 .../infer/annotation/PropagatesNullable.java       | 14 +++++++-------
 .../com/facebook/infer/annotation/TrueOnNull.java  | 10 +++++-----
 5 files changed, 27 insertions(+), 27 deletions(-)

diff --git a/infer/annotations/src/main/java/com/facebook/infer/annotation/Assertions.java b/infer/annotations/src/main/java/com/facebook/infer/annotation/Assertions.java
index 764c21bab..a77d74df2 100644
--- a/infer/annotations/src/main/java/com/facebook/infer/annotation/Assertions.java
+++ b/infer/annotations/src/main/java/com/facebook/infer/annotation/Assertions.java
@@ -22,7 +22,7 @@ public class Assertions {
   }
 
   /**
-   * See {@link #assertNotNull(T object, String explanation)}.
+   * See {@code #assertNotNull(T object, String explanation)}.
    *
    * <p>NOTE: prefer always providing an explanation.
    */
@@ -34,10 +34,10 @@ public class Assertions {
   }
 
   /**
-   * Same as {@link #assertNotNull()}, but does not do a runtime check. Useful in
+   * Same as {@code #assertNotNull()}, but does not do a runtime check. Useful in
    * performance-critical places when a runtime check is costly.
    *
-   * <p>NOTE: Whenever possible, prefer using {@link #assertNotNull()}. Java runtime is doing a good
+   * <p>NOTE: Whenever possible, prefer using {@code #assertNotNull()}. Java runtime is doing a good
    * job with optimizing nullability checks, so most likely this won't improve performance, but will
    * make unexpected null propagate and hide the real cause of an error.
    */
@@ -46,7 +46,7 @@ public class Assertions {
   }
 
   /**
-   * See {@link #assumeNotNull(T object, String explanation)}.
+   * See {@code #assumeNotNull(T object, String explanation)}.
    *
    * <p>NOTE: prefer always providing an explanation.
    */
@@ -56,7 +56,7 @@ public class Assertions {
 
   /**
    * Makes Nullsafe stop complaining when {@code object} is dereferenced or converted to a
-   * non-nullable. In contrast with {@link #assumeNotNull()}, indicates cases when the proper fix
+   * non-nullable. In contrast with {@code #assumeNotNull()}, indicates cases when the proper fix
    * needs to be committed, but for some reason it is hard or impossible to do it staight away.
    */
   public static <T> T nullsafeFIXME(@Nullable T object, String explanationOrTask) {
diff --git a/infer/annotations/src/main/java/com/facebook/infer/annotation/FalseOnNull.java b/infer/annotations/src/main/java/com/facebook/infer/annotation/FalseOnNull.java
index 96217230b..c482c59a0 100644
--- a/infer/annotations/src/main/java/com/facebook/infer/annotation/FalseOnNull.java
+++ b/infer/annotations/src/main/java/com/facebook/infer/annotation/FalseOnNull.java
@@ -12,6 +12,8 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+@Retention(RetentionPolicy.CLASS)
+@Target({ElementType.METHOD})
 /**
  * Annotation specifying method's contract. @FalseOnNull declares that a boolean method will always
  * return {@code false} when any of its arguments is {@code null}.
@@ -21,7 +23,7 @@ import java.lang.annotation.Target;
  *
  * <p>In the following example, annotating a method with @FalseOnNull simplifies its usage.
  *
- * <p><code>
+ * <pre>
  * @FalseOnNull
  * public static hasNotification(@Nullable MyObject object) {
  *  if (object == null) {
@@ -38,10 +40,8 @@ import java.lang.annotation.Target;
  *     obj.doSomething();
  *   }
  * }
- * </code>
+ * </pre>
  *
- * <p>See also @TrueOnNull and @PropagatesNullable annotations.
+ * <p>See also {@code @TrueOnNull} and {@code @PropagatesNullable} annotations.
  */
-@Retention(RetentionPolicy.CLASS)
-@Target({ElementType.METHOD})
 public @interface FalseOnNull {}
diff --git a/infer/annotations/src/main/java/com/facebook/infer/annotation/Initializer.java b/infer/annotations/src/main/java/com/facebook/infer/annotation/Initializer.java
index efcd12597..e5865707c 100644
--- a/infer/annotations/src/main/java/com/facebook/infer/annotation/Initializer.java
+++ b/infer/annotations/src/main/java/com/facebook/infer/annotation/Initializer.java
@@ -12,6 +12,8 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+@Retention(RetentionPolicy.CLASS)
+@Target({ElementType.TYPE, ElementType.FIELD, ElementType.CONSTRUCTOR, ElementType.METHOD})
 /**
  * A method annotated with @Initializer is expected to always be invoked before the object is used.
  * Nullsafe typechecker respects this annotation when checking field initialization: if a field is
@@ -24,7 +26,7 @@ import java.lang.annotation.Target;
  *
  * <p>In this example, only field2 will be reported as not initialized:
  *
- * <p><code>
+ * <pre>
  * class Example {
  *   private String field1;
  *   private String field2;
@@ -45,10 +47,8 @@ import java.lang.annotation.Target;
  *     field3 = "OK: Nullsafe assumes this will be called after creation";
  *   }
  * }
- * </code>
+ * </pre>
  *
- * <p>See also: @Cleanup annotation.
+ * <p>See also: {@code @Cleanup} annotation.
  */
-@Retention(RetentionPolicy.CLASS)
-@Target({ElementType.TYPE, ElementType.FIELD, ElementType.CONSTRUCTOR, ElementType.METHOD})
 public @interface Initializer {}
diff --git a/infer/annotations/src/main/java/com/facebook/infer/annotation/PropagatesNullable.java b/infer/annotations/src/main/java/com/facebook/infer/annotation/PropagatesNullable.java
index 889bb0205..a99a9cc43 100644
--- a/infer/annotations/src/main/java/com/facebook/infer/annotation/PropagatesNullable.java
+++ b/infer/annotations/src/main/java/com/facebook/infer/annotation/PropagatesNullable.java
@@ -12,6 +12,8 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+@Retention(RetentionPolicy.CLASS)
+@Target({ElementType.PARAMETER})
 /**
  * Annotation specifying method's contract. If a method's param is annotated
  * with @PropagaresNullable, it declares that the method will return {@code null} if and only if
@@ -24,7 +26,7 @@ import java.lang.annotation.Target;
  * <p>In the following example, annotating the param with @PropagatesNullable allows to simplify
  * usage of the method.
  *
- * <p><code>
+ * <pre>
  * public static String capitalize(@PropagatesNullable String input) {
  *   if (input == null) {
  *     return null;
@@ -38,13 +40,11 @@ import java.lang.annotation.Target;
  *   // assertNotNull(capitalize(nonnull)) would be required.
  *   capitalize(nonnull).contains("A");  // <-- OK: safe to dereference
  * }
- * </code>
+ * </pre>
  *
- * <p>If several params are annotated as @PropagatesNullable, the method should return {@code null}
- * if and only if any of those params is {@code null}.
+ * <p>If several params are annotated as {@code @PropagatesNullable}, the method should return
+ * {@code null} if and only if any of those params is {@code null}.
  *
- * <p>See also @TrueOnNull and @FalseOnNull annotations.
+ * <p>See also {@code @TrueOnNull} and {@code @FalseOnNull} annotations.
  */
-@Retention(RetentionPolicy.CLASS)
-@Target({ElementType.PARAMETER})
 public @interface PropagatesNullable {}
diff --git a/infer/annotations/src/main/java/com/facebook/infer/annotation/TrueOnNull.java b/infer/annotations/src/main/java/com/facebook/infer/annotation/TrueOnNull.java
index 463a0fa69..79b1faa41 100644
--- a/infer/annotations/src/main/java/com/facebook/infer/annotation/TrueOnNull.java
+++ b/infer/annotations/src/main/java/com/facebook/infer/annotation/TrueOnNull.java
@@ -12,6 +12,8 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+@Retention(RetentionPolicy.CLASS)
+@Target({ElementType.METHOD})
 /**
  * Annotation specifying method's contract. @TrueOnNull declares that a boolean method will always
  * return {@code true} when any of its arguments is {@code null}.
@@ -21,7 +23,7 @@ import java.lang.annotation.Target;
  *
  * <p>In the following example, annotating a method with @TrueOnNull simplifies its usage.
  *
- * <p><code>
+ * <pre>
  * @TrueOnNull
  * public static boolean isStringEmpty(@Nullable String str) {
  *   return str == null || str.length() == 0;
@@ -35,10 +37,8 @@ import java.lang.annotation.Target;
  *     myString.toUpperCase();
  *   }
  * }
- * </code>
+ * </pre>
  *
- * <p>See also @FalseOnNull and @PropagatesNullable annotations.
+ * <p>See also {@code @FalseOnNull} and {@code @PropagatesNullable} annotations.
  */
-@Retention(RetentionPolicy.CLASS)
-@Target({ElementType.METHOD})
 public @interface TrueOnNull {}