Add javadoc to enums

pgpainless-core/src/main/java/org/pgpainless/algorithm/CompressionAlgorithm.java

@@ -20,6 +20,11 @@ import java.util.concurrent.ConcurrentHashMap;
 
 import org.bouncycastle.bcpg.CompressionAlgorithmTags;
 
+/**
+ * Enumeration of possible compression algorithms.
+ *
+ * @see <a href="https://tools.ietf.org/html/rfc4880#section-9.3">RFC4880: Compression Algorithm Tags</a>
+ */
 public enum CompressionAlgorithm {
 
     UNCOMPRESSED   (CompressionAlgorithmTags.UNCOMPRESSED),
@@ -36,6 +41,13 @@ public enum CompressionAlgorithm {
         }
     }
 
+    /**
+     * Return the {@link CompressionAlgorithm} value that corresponds to the provided numerical id.
+     * If an invalid id is provided, null is returned.
+     *
+     * @param id id
+     * @return compression algorithm
+     */
     public static CompressionAlgorithm fromId(int id) {
         return MAP.get(id);
     }
@@ -46,6 +58,10 @@ public enum CompressionAlgorithm {
         this.algorithmId = id;
     }
 
+    /**
+     * Return the numerical algorithm tag corresponding to this compression algorithm.
+     * @return id
+     */
     public int getAlgorithmId() {
         return algorithmId;
     }

pgpainless-core/src/main/java/org/pgpainless/algorithm/Feature.java

@@ -20,6 +20,11 @@ import java.util.concurrent.ConcurrentHashMap;
 
 import org.bouncycastle.bcpg.sig.Features;
 
+/**
+ * An enumeration of features that may be set in the {@link Features} subpacket.
+ *
+ * @see <a href="https://tools.ietf.org/html/rfc4880#section-5.2.3.24">RFC4880: Features</a>
+ */
 public enum Feature {
 
     /**

pgpainless-core/src/main/java/org/pgpainless/algorithm/HashAlgorithm.java

@@ -20,8 +20,13 @@ import java.util.concurrent.ConcurrentHashMap;
 
 import org.bouncycastle.bcpg.HashAlgorithmTags;
 
+/**
+ * An enumeration of different hashing algorithms.
+ *
+ * @see <a href="https://tools.ietf.org/html/rfc4880#section-9.4">RFC4880: Hash Algorithms</a>
+ */
 public enum HashAlgorithm {
-
+    @Deprecated
     MD5        (HashAlgorithmTags.MD5),
     SHA1       (HashAlgorithmTags.SHA1),
     RIPEMD160  (HashAlgorithmTags.RIPEMD160),
@@ -43,6 +48,13 @@ public enum HashAlgorithm {
         }
     }
 
+    /**
+     * Return the {@link HashAlgorithm} value that corresponds to the provided algorithm id.
+     * If an invalid algorithm id was provided, null is returned.
+     *
+     * @param id numeric id
+     * @return enum value
+     */
     public static HashAlgorithm fromId(int id) {
         return MAP.get(id);
     }
@@ -53,6 +65,11 @@ public enum HashAlgorithm {
         this.algorithmId = id;
     }
 
+    /**
+     * Return the numeric algorithm id of the hash algorithm.
+     *
+     * @return numeric id
+     */
     public int getAlgorithmId() {
         return algorithmId;
     }

pgpainless-core/src/main/java/org/pgpainless/algorithm/KeyFlag.java

@@ -20,14 +20,47 @@ import java.util.List;
 
 import org.bouncycastle.bcpg.sig.KeyFlags;
 
+/**
+ * Enumeration of different key flags.
+ * Key flags denote different capabilities of a key pair.
+ *
+ * @see <a href="https://tools.ietf.org/html/rfc4880#section-5.2.3.21">RFC4880: Key Flags</a>
+ */
 public enum KeyFlag {
 
+    /**
+     * This key may be used to certify other keys.
+     */
     CERTIFY_OTHER  (KeyFlags.CERTIFY_OTHER),
+
+    /**
+     * This key may be used to sign data.
+     */
     SIGN_DATA      (KeyFlags.SIGN_DATA),
+
+    /**
+     * This key may be used to encrypt communications.
+     */
     ENCRYPT_COMMS  (KeyFlags.ENCRYPT_COMMS),
+
+    /**
+     * This key may be used to encrypt storage.
+     */
     ENCRYPT_STORAGE(KeyFlags.ENCRYPT_STORAGE),
+
+    /**
+     * The private component of this key may have been split by a secret-sharing mechanism.
+     */
     SPLIT          (KeyFlags.SPLIT),
+
+    /**
+     * This key may be used for authentication.
+     */
     AUTHENTICATION (KeyFlags.AUTHENTICATION),
+
+    /**
+     * The private component of this key may be in the possession of more than one person.
+     */
     SHARED         (KeyFlags.SHARED),
     ;
 
@@ -37,10 +70,21 @@ public enum KeyFlag {
         this.flag = flag;
     }
 
+    /**
+     * Return the numeric id of the {@link KeyFlag}.
+     *
+     * @return numeric id
+     */
     public int getFlag() {
         return flag;
     }
 
+    /**
+     * Convert a bitmask into a list of {@link KeyFlag KeyFlags}.
+     *
+     * @param bitmask bitmask
+     * @return list of key flags encoded by the bitmask
+     */
     public static List<KeyFlag> fromBitmask(int bitmask) {
         List<KeyFlag> flags = new ArrayList<>();
         for (KeyFlag f : KeyFlag.values()) {
@@ -51,6 +95,12 @@ public enum KeyFlag {
         return flags;
     }
 
+    /**
+     * Encode a list of {@link KeyFlag KeyFlags} into a bitmask.
+     *
+     * @param flags list of flags
+     * @return bitmask
+     */
     public static int toBitmask(KeyFlag... flags) {
         int mask = 0;
         for (KeyFlag f : flags) {
@@ -59,6 +109,14 @@ public enum KeyFlag {
         return mask;
     }
 
+    /**
+     * Return true if the provided bitmask has the bit for the provided flag set.
+     * Return false if the mask does not contain the flag.
+     *
+     * @param mask bitmask
+     * @param flag flag to be tested for
+     * @return true if flag is set, false otherwise
+     */
     public static boolean hasKeyFlag(int mask, KeyFlag flag) {
         return (mask & flag.getFlag()) == flag.getFlag();
     }

pgpainless-core/src/main/java/org/pgpainless/algorithm/PublicKeyAlgorithm.java

@@ -20,6 +20,11 @@ import java.util.concurrent.ConcurrentHashMap;
 
 import org.bouncycastle.bcpg.PublicKeyAlgorithmTags;
 
+/**
+ * Enumeration of public key algorithms as defined in RFC4880.
+ *
+ * @see <a href="https://tools.ietf.org/html/rfc4880#section-9.1">RFC4880: Public-Key Algorithms</a>
+ */
 public enum PublicKeyAlgorithm {
 
     /**
@@ -32,6 +37,7 @@ public enum PublicKeyAlgorithm {
      *
      * @deprecated see https://tools.ietf.org/html/rfc4880#section-13.5
      */
+    @Deprecated
     RSA_ENCRYPT     (PublicKeyAlgorithmTags.RSA_ENCRYPT),
 
     /**
@@ -39,6 +45,7 @@ public enum PublicKeyAlgorithm {
      *
      * @deprecated see https://tools.ietf.org/html/rfc4880#section-13.5
      */
+    @Deprecated
     RSA_SIGN        (PublicKeyAlgorithmTags.RSA_SIGN),
 
     /**
@@ -55,6 +62,7 @@ public enum PublicKeyAlgorithm {
      * EC is deprecated.
      * @deprecated use {@link #ECDH} instead.
      */
+    @Deprecated
     EC              (PublicKeyAlgorithmTags.EC),
 
     /**
@@ -94,6 +102,13 @@ public enum PublicKeyAlgorithm {
         }
     }
 
+    /**
+     * Return the {@link PublicKeyAlgorithm} that corresponds to the provided algorithm id.
+     * If an invalid id is provided, null is returned.
+     *
+     * @param id numeric algorithm id
+     * @return algorithm
+     */
     public static PublicKeyAlgorithm fromId(int id) {
         return MAP.get(id);
     }
@@ -104,6 +119,11 @@ public enum PublicKeyAlgorithm {
         this.algorithmId = algorithmId;
     }
 
+    /**
+     * Return the numeric identifier of the public key algorithm.
+     *
+     * @return id
+     */
     public int getAlgorithmId() {
         return algorithmId;
     }

pgpainless-core/src/main/java/org/pgpainless/algorithm/SignatureSubpacket.java

@@ -49,6 +49,11 @@ import java.util.List;
 import java.util.Map;
 import java.util.concurrent.ConcurrentHashMap;
 
+/**
+ * Enumeration of possible subpackets that might be found in the hashed and unhashed area of an OpenPGP signature.
+ *
+ * @see <a href="https://tools.ietf.org/html/rfc4880#section-5.2.3.1">RFC4880: Signature Subpacket Specification</a>
+ */
 public enum SignatureSubpacket {
 
     /**
@@ -408,10 +413,20 @@ public enum SignatureSubpacket {
         this.code = code;
     }
 
+    /**
+     * Return the numerical identifier of the {@link SignatureSubpacket}.
+     * @return id
+     */
     public int getCode() {
         return code;
     }
 
+    /**
+     * Return the {@link SignatureSubpacket} that corresponds to the provided id.
+     *
+     * @param code id
+     * @return signature subpacket
+     */
     public static SignatureSubpacket fromCode(int code) {
         SignatureSubpacket tag = MAP.get(code);
         if (tag == null) {
@@ -420,6 +435,12 @@ public enum SignatureSubpacket {
         return tag;
     }
 
+    /**
+     * Convert an array of signature subpacket tags into a list of {@link SignatureSubpacket SignatureSubpackets}.
+     *
+     * @param codes array of codes
+     * @return list of subpackets
+     */
     public static List<SignatureSubpacket> fromCodes(int[] codes) {
         List<SignatureSubpacket> tags = new ArrayList<>();
         for (int code : codes) {

pgpainless-core/src/main/java/org/pgpainless/algorithm/SignatureType.java

@@ -173,6 +173,12 @@ public enum SignatureType {
         }
     }
 
+    /**
+     * Convert a numerical id into a {@link SignatureType}.
+     *
+     * @param code numeric id
+     * @return signature type enum
+     */
     public static SignatureType valueOf(int code) {
         SignatureType type = map.get(code);
         if (type != null) {
@@ -187,6 +193,11 @@ public enum SignatureType {
         this.code = code;
     }
 
+    /**
+     * Return the numeric id of the signature type enum.
+     *
+     * @return numeric id
+     */
     public int getCode() {
         return code;
     }

pgpainless-core/src/main/java/org/pgpainless/algorithm/StreamEncoding.java

@@ -21,14 +21,33 @@ import java.util.concurrent.ConcurrentHashMap;
 import org.bouncycastle.openpgp.PGPLiteralData;
 
 /**
- * Encoding of the stream.
+ * Enumeration of possible encoding formats of the content of the literal data packet.
  *
  * @see <a href="https://tools.ietf.org/html/rfc4880#section-5.9">RFC4880: Literal Data Packet</a>
  */
 public enum StreamEncoding {
+
+    /**
+     * The Literal packet contains binary data.
+     */
     BINARY(PGPLiteralData.BINARY),
+
+    /**
+     * The Literal packet contains text data, and thus may need line ends converted to local form, or other
+     * text-mode changes.
+     */
     TEXT(PGPLiteralData.TEXT),
+
+    /**
+     * Indication that the implementation believes that the literal data contains UTF-8 text.
+     */
     UTF8(PGPLiteralData.UTF8),
+
+    /**
+     * Early versions of PGP also defined a value of 'l' as a 'local' mode for machine-local conversions.
+     * RFC 1991 [RFC1991] incorrectly stated this local mode flag as '1' (ASCII numeral one).
+     * Both of these local modes are deprecated.
+     */
     @Deprecated
     LOCAL('l'),
     ;
@@ -40,6 +59,7 @@ public enum StreamEncoding {
         for (StreamEncoding f : StreamEncoding.values()) {
             MAP.put(f.code, f);
         }
+        // RFC 1991 [RFC1991] incorrectly stated local mode flag as '1', see doc of LOCAL.
         MAP.put('1', LOCAL);
     }
 
@@ -47,10 +67,21 @@ public enum StreamEncoding {
         this.code = code;
     }
 
+    /**
+     * Return the code identifier of the encoding.
+     *
+     * @return identifier
+     */
     public char getCode() {
         return code;
     }
 
+    /**
+     * Return the {@link StreamEncoding} corresponding to the provided code identifier.
+     *
+     * @param code identifier
+     * @return encoding enum
+     */
     public static StreamEncoding fromCode(int code) {
         return MAP.get((char) code);
     }

pgpainless-core/src/main/java/org/pgpainless/algorithm/SymmetricKeyAlgorithm.java

@@ -20,25 +20,85 @@ import java.util.concurrent.ConcurrentHashMap;
 
 import org.bouncycastle.bcpg.SymmetricKeyAlgorithmTags;
 
+/**
+ * Enumeration of possible symmetric encryption algorithms.
+ *
+ * @see <a href="https://tools.ietf.org/html/rfc4880#section-9.2">RFC4880: Symmetric-Key Algorithms</a>
+ */
 public enum SymmetricKeyAlgorithm {
 
+    /**
+     * Plaintext or unencrypted data.
+     */
     NULL            (SymmetricKeyAlgorithmTags.NULL),
+
     /**
      * IDEA is deprecated.
      * @deprecated use a different algorithm.
      */
+    @Deprecated
     IDEA            (SymmetricKeyAlgorithmTags.IDEA),
+
+    /**
+     * TripleDES (DES-EDE - 168 bit key derived from 192).
+     */
     TRIPLE_DES      (SymmetricKeyAlgorithmTags.TRIPLE_DES),
+
+    /**
+     * CAST5 (128 bit key, as per RFC2144).
+     */
     CAST5           (SymmetricKeyAlgorithmTags.CAST5),
+
+    /**
+     * Blowfish (128 bit key, 16 rounds).
+     */
     BLOWFISH        (SymmetricKeyAlgorithmTags.BLOWFISH),
+
+    /**
+     * Reserved in RFC4880.
+     * SAFER-SK128 (13 rounds)
+     */
     SAFER           (SymmetricKeyAlgorithmTags.SAFER),
+
+    /**
+     * Reserved in RFC4880.
+     * Reserved for DES/SK
+     */
     DES             (SymmetricKeyAlgorithmTags.DES),
+
+    /**
+     * AES with 128-bit key.
+     */
     AES_128         (SymmetricKeyAlgorithmTags.AES_128),
+
+    /**
+     * AES with 192-bit key.
+     */
     AES_192         (SymmetricKeyAlgorithmTags.AES_192),
+
+    /**
+     * AES with 256-bit key.
+     */
     AES_256         (SymmetricKeyAlgorithmTags.AES_256),
+
+    /**
+     * Twofish with 256-bit key.
+     */
     TWOFISH         (SymmetricKeyAlgorithmTags.TWOFISH),
+
+    /**
+     * Reserved for Camellia with 128-bit key.
+     */
     CAMELLIA_128    (SymmetricKeyAlgorithmTags.CAMELLIA_128),
+
+    /**
+     * Reserved for Camellia with 192-bit key.
+     */
     CAMELLIA_192    (SymmetricKeyAlgorithmTags.CAMELLIA_192),
+
+    /**
+     * Reserved for Camellia with 256-bit key.
+     */
     CAMELLIA_256    (SymmetricKeyAlgorithmTags.CAMELLIA_256),
     ;
 
@@ -50,6 +110,13 @@ public enum SymmetricKeyAlgorithm {
         }
     }
 
+    /**
+     * Return the {@link SymmetricKeyAlgorithm} enum that corresponds to the provided numeric id.
+     * If an invalid id is provided, null is returned.
+     *
+     * @param id numeric algorithm id
+     * @return symmetric key algorithm enum
+     */
     public static SymmetricKeyAlgorithm fromId(int id) {
         return MAP.get(id);
     }
@@ -60,6 +127,11 @@ public enum SymmetricKeyAlgorithm {
         this.algorithmId = algorithmId;
     }
 
+    /**
+     * Return the numeric algorithm id of the enum.
+     *
+     * @return numeric id
+     */
     public int getAlgorithmId() {
         return algorithmId;
     }