[SDK-3159] JavaDoc updated

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

@@ -13,12 +13,12 @@ private HeaderParams() {}
     public static String ALGORITHM = "alg";
 
     /**
-     * The content type of a JWT.
+     * The content type of the JWT.
      */
     public static String CONTENT_TYPE = "cty";
 
     /**
-     * The media type of a JWT.
+     * The media type of the JWT.
      */
     public static String TYPE = "typ";
 

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

@@ -26,7 +26,7 @@ public JWT() {
      * Decode a given Json Web Token.
      * <p>
      * Note that this method <b>doesn't verify the token's signature!</b>
-     * Use it only if you trust the token or you already verified it.
+     * Use it only if you trust the token or if you have already verified it.
      *
      * @param token with jwt format as string.
      * @return a decoded JWT.
@@ -41,7 +41,7 @@ public DecodedJWT decodeJwt(String token) throws JWTDecodeException {
      * Decode a given Json Web Token.
      * <p>
      * Note that this method <b>doesn't verify the token's signature!</b>
-     * Use it only if you trust the token or you already verified it.
+     * Use it only if you trust the token or if you have already verified it.
      *
      * @param token with jwt format as string.
      * @return a decoded JWT.
@@ -53,10 +53,10 @@ public static DecodedJWT decode(String token) throws JWTDecodeException {
     }
 
     /**
-     * Returns a {@link JWTVerifier} builder with the algorithm to be used to validate token signature.
+     * Returns a {@link Verification} builder with the algorithm to be used to validate token signature.
      *
      * @param algorithm that will be used to verify the token's signature.
-     * @return {@link JWTVerifier} builder
+     * @return {@link Verification} builder
      * @throws IllegalArgumentException if the provided algorithm is null.
      */
     public static Verification require(Algorithm algorithm) {

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

@@ -35,10 +35,10 @@ public final class JWTVerifier implements com.auth0.jwt.interfaces.JWTVerifier {
     }
 
     /**
-     * Initialize a JWTVerifier instance using the given Algorithm.
+     * Initialize a {@link Verification} instance using the given Algorithm.
      *
      * @param algorithm the Algorithm to use on the JWT verification.
-     * @return a JWTVerifier.Verification instance to configure.
+     * @return a {@link Verification} instance to configure.
      * @throws IllegalArgumentException if the provided algorithm is null.
      */
     static Verification init(Algorithm algorithm) throws IllegalArgumentException {

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

@@ -1,7 +1,7 @@
 package com.auth0.jwt;
 
 /**
- * Contains constants representing the name of the Registered Claim Names as defined in Section 4.1.1 of
+ * Contains constants representing the name of the Registered Claim Names as defined in Section 4.1 of
  * <a href="https://datatracker.ietf.org/doc/html/rfc7519#section-4.1">RFC 7529</a>
  */
 public final class RegisteredClaims {
@@ -11,37 +11,44 @@ private RegisteredClaims() {
 
     /**
      * The "iss" (issuer) claim identifies the principal that issued the JWT.
+     * Refer RFC 7529 <a href="https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.1">Section 4.1.1</a>
      */
     public static String ISSUER = "iss";
 
     /**
      * The "sub" (subject) claim identifies the principal that is the subject of the JWT.
+     * Refer RFC 7529 <a href="https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.2">Section 4.1.2</a>
      */
     public static String SUBJECT = "sub";
 
     /**
      * The "aud" (audience) claim identifies the recipients that the JWT is intended for.
+     * Refer RFC 7529 <a href="https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.3">Section 4.1.3</a>
      */
     public static String AUDIENCE = "aud";
 
     /**
      * The "exp" (expiration time) claim identifies the expiration time on or after which the JWT MUST NOT be
      * accepted for processing.
+     * Refer RFC 7529 <a href="https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4">Section 4.1.4</a>
      */
     public static String EXPIRES_AT = "exp";
 
     /**
      * The "nbf" (not before) claim identifies the time before which the JWT MUST NOT be accepted for processing.
+     * Refer RFC 7529 <a href="https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.5">Section 4.1.5</a>
      */
     public static String NOT_BEFORE = "nbf";
 
     /**
      * The "iat" (issued at) claim identifies the time at which the JWT was issued.
+     * Refer RFC 7529 <a href="https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.6">Section 4.1.6</a>
      */
     public static String ISSUED_AT = "iat";
 
     /**
      * The "jti" (JWT ID) claim provides a unique identifier for the JWT.
+     * Refer RFC 7529 <a href="https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.7">Section 4.1.7</a>
      */
     public static String JWT_ID = "jti";
 

lib/src/main/java/com/auth0/jwt/impl/PayloadSerializer.java

@@ -34,8 +34,6 @@ protected void writeClaim(Map.Entry<String, Object> entry, JsonGenerator gen) th
      * Audience may be a list of strings or a single string. This is needed to properly handle the aud claim when
      * added with the {@linkplain com.auth0.jwt.JWTCreator.Builder#withPayload(Map)} method.
      */
-
-    //
     private void writeAudience(JsonGenerator gen, Map.Entry<String, Object> e) throws IOException {
         if (e.getValue() instanceof String) {
             gen.writeFieldName(e.getKey());

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

@@ -22,63 +22,63 @@ public interface Claim {
 
     /**
      * Can be used to verify whether the Claim is found or not.
-     * This will be true even if the Claim has null value associated to it.
+     * This will be true even if the Claim has {@code null} value associated to it.
      *
      * @return whether this Claim is present or not
      */
     boolean isMissing();
 
     /**
      * Get this Claim as a Boolean.
-     * If the value isn't of type Boolean or it can't be converted to a Boolean, null will be returned.
+     * If the value isn't of type Boolean or it can't be converted to a Boolean, {@code null} will be returned.
      *
      * @return the value as a Boolean or null.
      */
     Boolean asBoolean();
 
     /**
      * Get this Claim as an Integer.
-     * If the value isn't of type Integer or it can't be converted to an Integer, null will be returned.
+     * If the value isn't of type Integer or it can't be converted to an Integer, {@code null} will be returned.
      *
      * @return the value as an Integer or null.
      */
     Integer asInt();
 
     /**
      * Get this Claim as an Long.
-     * If the value isn't of type Long or it can't be converted to an Long, null will be returned.
+     * If the value isn't of type Long or it can't be converted to a Long, {@code null} will be returned.
      *
      * @return the value as an Long or null.
      */
     Long asLong();
 
     /**
      * Get this Claim as a Double.
-     * If the value isn't of type Double or it can't be converted to a Double, null will be returned.
+     * If the value isn't of type Double or it can't be converted to a Double, {@code null} will be returned.
      *
      * @return the value as a Double or null.
      */
     Double asDouble();
 
     /**
      * Get this Claim as a String.
-     * If the value isn't of type String or it can't be converted to a String, null will be returned.
+     * If the value isn't of type String or it can't be converted to a String, {@code null} will be returned.
      *
      * @return the value as a String or null.
      */
     String asString();
 
     /**
      * Get this Claim as a Date.
-     * If the value can't be converted to a Date, null will be returned.
+     * If the value can't be converted to a Date, {@code null} will be returned.
      *
      * @return the value as a Date or null.
      */
     Date asDate();
 
     /**
      * Get this Claim as an Instant.
-     * If the value can't be converted to an Instant, null will be returned.
+     * If the value can't be converted to an Instant, {@code null} will be returned.
      *
      * @return the value as a Date or null.
      */
@@ -89,7 +89,7 @@ default Instant asInstant() {
 
     /**
      * Get this Claim as an Array of type T.
-     * If the value isn't an Array, null will be returned.
+     * If the value isn't an Array, {@code null} will be returned.
      *
      * @param <T> type
      * @param clazz the type class
@@ -100,7 +100,7 @@ default Instant asInstant() {
 
     /**
      * Get this Claim as a List of type T.
-     * If the value isn't an Array, null will be returned.
+     * If the value isn't an Array, {@code null} will be returned.
      *
      * @param <T> type
      * @param clazz the type class

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

@@ -1,7 +1,7 @@
 package com.auth0.jwt.interfaces;
 
 /**
- * The Header class represents the 1st part of the JWT, where the Header value is hold.
+ * The Header class represents the 1st part of the JWT, where the Header value is held.
  */
 public interface Header {
 
@@ -35,7 +35,7 @@ public interface Header {
 
     /**
      * Get a Private Claim given it's name. If the Claim wasn't specified in the Header, a 'null claim' will be
-     * returned. All of the methods of that claim will return {@code null}.
+     * returned. All the methods of that claim will return {@code null}.
      *
      * @param name the name of the Claim to retrieve.
      * @return a non-null Claim.

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

@@ -4,12 +4,12 @@
 
 /**
  * The JWTPartsParser class defines which parts of the JWT should be converted
- * to it's specific Object representation instance.
+ * to its specific Object representation instance.
  */
 public interface JWTPartsParser {
 
     /**
-     * Parses the given JSON into a Payload instance.
+     * Parses the given JSON into a {@link Payload} instance.
      *
      * @param json the content of the Payload in a JSON representation.
      * @return the Payload.
@@ -18,7 +18,7 @@ public interface JWTPartsParser {
     Payload parsePayload(String json) throws JWTDecodeException;
 
     /**
-     * Parses the given JSON into a Header instance.
+     * Parses the given JSON into a {@link Header} instance.
      *
      * @param json the content of the Header in a JSON representation.
      * @return the Header.

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

@@ -4,7 +4,7 @@
 
 
 /**
- * Used to verify the JWT for it's signature and claims.
+ * Used to verify the JWT for its signature and claims.
  */
 public interface JWTVerifier {
 
@@ -18,7 +18,7 @@ public interface JWTVerifier {
     DecodedJWT verify(String token) throws JWTVerificationException;
 
     /**
-     * Performs the verification against the given decoded JWT.
+     * Performs the verification against the given {@link DecodedJWT}.
      *
      * @param jwt to verify.
      * @return a verified and decoded JWT.

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

@@ -5,6 +5,7 @@
 
 /**
  * Generic Public/Private Key provider.
+ * While implementing, ensure the Private Key and Private Key ID doesn't change in between signing a token.
  *
  * @param <U> the class that represents the Public Key
  * @param <R> the class that represents the Private Key

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

@@ -6,7 +6,7 @@
 import java.util.Map;
 
 /**
- * The Payload class represents the 2nd part of the JWT, where the Payload value is hold.
+ * The Payload class represents the 2nd part of the JWT, where the Payload value is held.
  */
 public interface Payload {
 
@@ -87,8 +87,8 @@ default Instant getIssuedAtAsInstant() {
     String getId();
 
     /**
-     * Get a Claim given it's name. If the Claim wasn't specified in the Payload, a 'null claim'
-     * will be returned. All of the methods of that claim will return {@code null}.
+     * Get a Claim given its name. If the Claim wasn't specified in the Payload, a 'null claim'
+     * will be returned. All the methods of that claim will return {@code null}.
      *
      * @param name the name of the Claim to retrieve.
      * @return a non-null Claim.