[SDK-3816] Update docs for verification thread-safety

Author: jimmyjames

lib/src/main/java/com/auth0/jwt/JWTVerifier.java

@@ -46,7 +46,11 @@ static Verification init(Algorithm algorithm) throws IllegalArgumentException {
     }
 
     /**
-     * {@link Verification} implementation that accepts all the expected Claim values for verification.
+     * {@link Verification} implementation that accepts all the expected Claim values for verification, and
+     * builds a {@link com.auth0.jwt.interfaces.JWTVerifier} used to verify a JWT's signature and expected claims.
+     *
+     * Note that this class is <strong>not</strong> thread-safe. Calling {@link #build()} returns an instance of
+     * {@link com.auth0.jwt.interfaces.JWTVerifier} which can be reused.
      */
     public static class BaseVerification implements Verification {
         private final Algorithm algorithm;

lib/src/main/java/com/auth0/jwt/interfaces/JWTVerifier.java

@@ -4,7 +4,19 @@
 
 
 /**
- * Used to verify the JWT for its signature and claims.
+ * Used to verify the JWT for its signature and claims. Implementations must be thread-safe. Instances are created
+ * using {@link Verification}.
+ *
+ * <pre>
+ * try {
+ *      JWTVerifier verifier = JWTVerifier.init(Algorithm.RSA256(publicKey, privateKey)
+ *          .withIssuer("auth0")
+ *          .build();
+ *      DecodedJWT jwt = verifier.verify("token");
+ * } catch (JWTVerificationException e) {
+ *      // invalid signature or claims
+ * }
+ * </pre>
  */
 public interface JWTVerifier {
 

lib/src/main/java/com/auth0/jwt/interfaces/Verification.java

@@ -7,7 +7,9 @@
 import java.util.function.BiPredicate;
 
 /**
- * Constructs and holds the checks required for a JWT to be considered valid.
+ * Constructs and holds the checks required for a JWT to be considered valid. Note that implementations are
+ * <strong>not</strong> thread-safe. Once built by calling {@link #build()}, the resulting
+ * {@link com.auth0.jwt.interfaces.JWTVerifier} is thread-safe.
  */
 public interface Verification {