Issue-52 Improving Javadoc for compression

src/main/java/io/jsonwebtoken/CompressionCodec.java

@@ -19,6 +19,8 @@ package io.jsonwebtoken;
  * Defines how to compress and decompress byte arrays.
  *
  * @since 0.5.2
+ * @see io.jsonwebtoken.impl.compression.DeflateCompressionCodec
+ * @see io.jsonwebtoken.impl.compression.GzipCompressionCodec
  */
 public interface CompressionCodec {
 

src/main/java/io/jsonwebtoken/Header.java

@@ -103,8 +103,25 @@ public interface Header<T extends Header<T>> extends Map<String,Object> {
      */
     T setContentType(String cty);
 
+    /**
+     * Returns the JWT <code>calg</code> (Compression Algorithm) header value or {@code null} if not present.
+     *
+     * @return the {@code calg} header parameter value or {@code null} if not present.
+     * @since 0.5.2
+     */
     String getCompressionAlgorithm();
 
-    T setCompressionAlgorithm(String compressionAlgorithm);
+    /**
+     * Sets the JWT <code>calg</code> (Compression Algorithm) header parameter value. A {@code null} value will remove
+     * the property from the JSON map.
+     * <p>
+     * <p>The compression algorithm is NOT part of the <a href="https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-25>JWT specification</a>
+     * and must be used carefully since, is not expected that other libraries (including previous versions of this one)
+     * be able to deserialize a compressed JTW body correctly. </p>
+     *
+     * @param calg the JWT compression algorithm {@code calg} value or {@code null} to remove the property from the JSON map.
+     * @since 0.5.2
+     */
+    T setCompressionAlgorithm(String calg);
 
 }

src/main/java/io/jsonwebtoken/JwtBuilder.java

@@ -350,7 +350,10 @@ public interface JwtBuilder extends ClaimsMutator<JwtBuilder> {
     JwtBuilder signWith(SignatureAlgorithm alg, Key key);
 
     /**
-     * Compresses the JWT body before being signed.
+     * Compresses the JWT body using the {@link CompressionCodec} passed as argument.
+     *
+     * Note: Compression is not part of the Json Web Token specification and is not expected that other libraries (including
+     * older versions of this one) are able to consume a compressed JWT body correctly.
      *
      * @param codec implementation of the {@link CompressionCodec} to be used.
      * @return the builder for method chaining.

src/main/java/io/jsonwebtoken/JwtParser.java

@@ -206,8 +206,10 @@ public interface JwtParser {
     JwtParser setSigningKeyResolver(SigningKeyResolver signingKeyResolver);
 
     /**
+     * Sets the {@link CompressionCodecResolver} used to acquire the {@link CompressionCodec} that should be used to verify
+     * a decompress the JWT body. If the parsed JWT is not compressed, this resolver si not used.
      *
-     * @param compressionCodecResolver
+     * @param compressionCodecResolver  the compression codec resolver used to decompress the JWT body.
      * @return the parser for method chaining.
      * @since 0.5.2
      */