From fa9b07d2ce00731dafdb1f15e71b4d40577965f2 Mon Sep 17 00:00:00 2001
From: Paul Schaub <vanitasvitae@fsfe.org>
Date: Fri, 2 Feb 2024 18:49:56 +0100
Subject: [PATCH] Add documentation for toSecretKey method

---
 .../pgpainless/key/generation/GenerateOpenPgpKey.kt    |  8 ++++++++
 .../org/pgpainless/key/generation/type/KeyType.kt      | 10 ++--------
 .../org/pgpainless/key/generation/type/eddsa/EdDSA.kt  |  5 +----
 .../org/pgpainless/key/generation/type/xdh/XDH.kt      |  5 +----
 4 files changed, 12 insertions(+), 16 deletions(-)

diff --git a/pgpainless-core/src/main/kotlin/org/pgpainless/key/generation/GenerateOpenPgpKey.kt b/pgpainless-core/src/main/kotlin/org/pgpainless/key/generation/GenerateOpenPgpKey.kt
index 66f82638..401f03e7 100644
--- a/pgpainless-core/src/main/kotlin/org/pgpainless/key/generation/GenerateOpenPgpKey.kt
+++ b/pgpainless-core/src/main/kotlin/org/pgpainless/key/generation/GenerateOpenPgpKey.kt
@@ -270,6 +270,14 @@ open class GenerateOpenPgpKey(
                         }))
         }
 
+        /**
+         * Convert a [OpenPgpComponentKeyBuilder.V4ComponentKeyBuilder] to a version 4
+         * [PGPSecretKey].
+         *
+         * @param key builder
+         * @param isPrimaryKey if true, the result will be a primary key, a subkey otherwise.
+         * @param encryptor encryptor to protect the secret key. Can be null for unencrypted keys.
+         */
         private fun toSecretKey(
             key: OpenPgpComponentKeyBuilder.V4ComponentKeyBuilder<*>,
             isPrimaryKey: Boolean,
diff --git a/pgpainless-core/src/main/kotlin/org/pgpainless/key/generation/type/KeyType.kt b/pgpainless-core/src/main/kotlin/org/pgpainless/key/generation/type/KeyType.kt
index 3e0d7d71..0f80d5a9 100644
--- a/pgpainless-core/src/main/kotlin/org/pgpainless/key/generation/type/KeyType.kt
+++ b/pgpainless-core/src/main/kotlin/org/pgpainless/key/generation/type/KeyType.kt
@@ -100,16 +100,10 @@ interface KeyType {
 
         @JvmStatic fun ECDSA(curve: EllipticCurve): ECDSA = ECDSA.fromCurve(curve)
 
-        /**
-         * Legacy EdDSA using Ed25519.
-         * For OpenPGP v4 only.
-         */
+        /** Legacy EdDSA using Ed25519. For OpenPGP v4 only. */
         @JvmStatic fun EDDSA(curve: EdDSACurve): EdDSA = EdDSA.fromCurve(curve)
 
-        /**
-         * Legacy ECDH using Curve25519.
-         * For OpenPGP v4 only.
-         */
+        /** Legacy ECDH using Curve25519. For OpenPGP v4 only. */
         @JvmStatic fun XDH(curve: XDHSpec): XDH = XDH.fromSpec(curve)
 
         // TODO: Add crypto-refresh X25519, X448, Ed25519, Ed448
diff --git a/pgpainless-core/src/main/kotlin/org/pgpainless/key/generation/type/eddsa/EdDSA.kt b/pgpainless-core/src/main/kotlin/org/pgpainless/key/generation/type/eddsa/EdDSA.kt
index c5b612cb..28df6dee 100644
--- a/pgpainless-core/src/main/kotlin/org/pgpainless/key/generation/type/eddsa/EdDSA.kt
+++ b/pgpainless-core/src/main/kotlin/org/pgpainless/key/generation/type/eddsa/EdDSA.kt
@@ -8,10 +8,7 @@ import org.bouncycastle.jce.spec.ECNamedCurveGenParameterSpec
 import org.pgpainless.algorithm.PublicKeyAlgorithm
 import org.pgpainless.key.generation.type.KeyType
 
-/**
- * Legacy EdDSA using Ed25519.
- * For use with OpenPGP v4 only.
- */
+/** Legacy EdDSA using Ed25519. For use with OpenPGP v4 only. */
 class EdDSA private constructor(val curve: EdDSACurve) : KeyType {
     override val name = "EdDSA"
     override val algorithm = PublicKeyAlgorithm.EDDSA
diff --git a/pgpainless-core/src/main/kotlin/org/pgpainless/key/generation/type/xdh/XDH.kt b/pgpainless-core/src/main/kotlin/org/pgpainless/key/generation/type/xdh/XDH.kt
index 917ef14a..306e0e13 100644
--- a/pgpainless-core/src/main/kotlin/org/pgpainless/key/generation/type/xdh/XDH.kt
+++ b/pgpainless-core/src/main/kotlin/org/pgpainless/key/generation/type/xdh/XDH.kt
@@ -8,10 +8,7 @@ import org.bouncycastle.jce.spec.ECNamedCurveGenParameterSpec
 import org.pgpainless.algorithm.PublicKeyAlgorithm
 import org.pgpainless.key.generation.type.KeyType
 
-/**
- * Legacy ECDH with Curve25519.
- * For use with OpenPGP v4 only.
- */
+/** Legacy ECDH with Curve25519. For use with OpenPGP v4 only. */
 class XDH private constructor(spec: XDHSpec) : KeyType {
     override val name = "XDH"
     override val algorithm = PublicKeyAlgorithm.ECDH