Rename some classes

pgpainless-core/src/main/kotlin/org/pgpainless/key/generation/GenerateOpenPgpKey.kt

@@ -35,6 +35,9 @@ open class GenerateOpenPgpKey(
     private val preferences: AlgorithmSuite = policy.keyGenerationAlgorithmSuite
 ) {
 
+    /**
+     * Builder for OpenPGP secret keys.
+     */
     abstract class OpenPgpKeyBuilder(
         protected val policy: Policy,
         protected val referenceTime: Date,
@@ -97,8 +100,8 @@ open class GenerateOpenPgpKey(
         }
 
         private val primaryKey =
-            BaseOpenPgpKeyBuilder.BaseV4PrimaryKeyBuilder(primaryKeyType, referenceTime, policy)
-        private val subkeys = mutableListOf<BaseOpenPgpKeyBuilder.BaseV4SubkeyBuilder>()
+            OpenPgpComponentKeyBuilder.V4PrimaryKeyBuilder(primaryKeyType, referenceTime, policy)
+        private val subkeys = mutableListOf<OpenPgpComponentKeyBuilder.V4SubkeyBuilder>()
 
         private val preferencesCallback =
             SelfSignatureSubpackets.applyHashed {
@@ -183,7 +186,7 @@ open class GenerateOpenPgpKey(
             subpacketsCallback: SelfSignatureSubpackets.Callback = SelfSignatureSubpackets.nop()
         ) =
             addSubkey(
-                BaseOpenPgpKeyBuilder.BaseV4SubkeyBuilder(
+                OpenPgpComponentKeyBuilder.V4SubkeyBuilder(
                     keyType, creationTime, policy, primaryKey),
                 SelfSignatureSubpackets.applyHashed {
                         setSignatureCreationTime(bindingTime)
@@ -192,13 +195,23 @@ open class GenerateOpenPgpKey(
                     .then(subpacketsCallback))
 
         fun addSubkey(
-            subkeyBuilder: BaseOpenPgpKeyBuilder.BaseV4SubkeyBuilder,
+            subkeyBuilder: OpenPgpComponentKeyBuilder.V4SubkeyBuilder,
             subpacketsCallback: SelfSignatureSubpackets.Callback = SelfSignatureSubpackets.nop()
         ) = apply {
             sanitizePublicKeyAlgorithms(subkeyBuilder.type, policy)
             subkeys.add(subkeyBuilder.bindingSignature(subpacketsCallback = subpacketsCallback))
         }
 
+        /**
+         * Add a new subkey to be used for encryption.
+         * The binding signature will mark the key as encryption-capable using both
+         * [KeyFlag.ENCRYPT_COMMS] and [KeyFlag.ENCRYPT_STORAGE].
+         *
+         * @param keyType type of the encryption subkey
+         * @param creationTime time of creation of the subkey
+         * @param bindingTime creation time of the binding signature
+         * @return builder
+         */
         fun addEncryptionSubkey(
             keyType: KeyType,
             creationTime: Date = referenceTime,
@@ -210,12 +223,31 @@ open class GenerateOpenPgpKey(
                 bindingTime,
                 listOf(KeyFlag.ENCRYPT_STORAGE, KeyFlag.ENCRYPT_COMMS))
 
+        /**
+         * Add a new subkey to be used for creating data signatures.
+         * The binding signature will mark the key as signing-capable using [KeyFlag.SIGN_DATA].
+         *
+         * @param keyType type of the signing subkey
+         * @param creationTime time of creation of the subkey
+         * @param bindingTime creation time of the binding signature
+         * @return builder
+         */
         fun addSigningSubkey(
             keyType: KeyType,
             creationTime: Date = referenceTime,
             bindingTime: Date = creationTime
         ) = addSubkey(keyType, creationTime, bindingTime, listOf(KeyFlag.SIGN_DATA))
 
+        /**
+         * Build the finished OpenPGP key.
+         * By default, the key will not be protected using passphrases.
+         * To set a passphrase, you can provide [SecretKeyRingProtector.unlockAnyKeyWith] with
+         * a passphrase of your choice.
+         *
+         * @param protector protector to secure the secret keys using passphrases.
+         * Defaults to [SecretKeyRingProtector.unprotectedKeys].
+         * @return OpenPGP Secret Key
+         */
         fun build(
             protector: SecretKeyRingProtector = SecretKeyRingProtector.unprotectedKeys()
         ): PGPSecretKeyRing {
@@ -233,7 +265,7 @@ open class GenerateOpenPgpKey(
         }
 
         private fun toSecretKey(
-            key: BaseOpenPgpKeyBuilder.BaseV4KeyBuilder<*>,
+            key: OpenPgpComponentKeyBuilder.V4ComponentKeyBuilder<*>,
             isPrimaryKey: Boolean,
             encryptor: PBESecretKeyEncryptor?
         ): PGPSecretKey {

pgpainless-core/src/main/kotlin/org/pgpainless/key/generation/OpenPgpComponentKeyBuilder.kt

@@ -26,9 +26,9 @@ import org.pgpainless.signature.builder.SelfSignatureBuilder
 import org.pgpainless.signature.builder.SubkeyBindingSignatureBuilder
 import org.pgpainless.signature.subpackets.SelfSignatureSubpackets
 
-class BaseOpenPgpKeyBuilder {
+class OpenPgpComponentKeyBuilder {
 
-    abstract class BaseV4KeyBuilder<T : BaseV4KeyBuilder<T>>(
+    abstract class V4ComponentKeyBuilder<T : V4ComponentKeyBuilder<T>>(
         val type: KeyType,
         val creationTime: Date,
         val certificateCreationTime: Date = Date(),
@@ -40,9 +40,9 @@ class BaseOpenPgpKeyBuilder {
         fun subkey(
             type: KeyType,
             creationTime: Date = certificateCreationTime
-        ): BaseV4SubkeyBuilder = BaseV4SubkeyBuilder(type, creationTime, policy, primaryKey())
+        ): V4SubkeyBuilder = V4SubkeyBuilder(type, creationTime, policy, primaryKey())
 
-        internal abstract fun primaryKey(): BaseV4PrimaryKeyBuilder
+        internal abstract fun primaryKey(): V4PrimaryKeyBuilder
 
         // Note: The result is a *primary* key pair, so subkeys need adjustment (toPrimaryOrSubkey)
         private fun generateKeyPair(): PGPKeyPair {
@@ -65,8 +65,8 @@ class BaseOpenPgpKeyBuilder {
         protected abstract fun toPrimaryOrSubkey(keyPair: PGPKeyPair): PGPKeyPair
     }
 
-    class BaseV4PrimaryKeyBuilder(type: KeyType, creationTime: Date, policy: Policy) :
-        BaseV4KeyBuilder<BaseV4PrimaryKeyBuilder>(type, creationTime, policy = policy) {
+    class V4PrimaryKeyBuilder(type: KeyType, creationTime: Date, policy: Policy) :
+        V4ComponentKeyBuilder<V4PrimaryKeyBuilder>(type, creationTime, policy = policy) {
 
         fun userId(
             userId: CharSequence,
@@ -179,12 +179,12 @@ class BaseOpenPgpKeyBuilder {
         override fun primaryKey() = this
     }
 
-    class BaseV4SubkeyBuilder(
+    class V4SubkeyBuilder(
         type: KeyType,
         creationTime: Date,
         policy: Policy,
-        private val primaryKeyBuilder: BaseV4PrimaryKeyBuilder
-    ) : BaseV4KeyBuilder<BaseV4SubkeyBuilder>(type, creationTime, policy = policy) {
+        private val primaryKeyBuilder: V4PrimaryKeyBuilder
+    ) : V4ComponentKeyBuilder<V4SubkeyBuilder>(type, creationTime, policy = policy) {
 
         fun bindingSignature(
             bindingTime: Date = creationTime,