Update documentation (#71)

benchmarks/src/commonMain/kotlin/org/kotlincrypto/core/benchmarks/DigestBenchmark.kt

@@ -16,7 +16,6 @@
 package org.kotlincrypto.core.benchmarks
 
 import kotlinx.benchmark.*
-import org.kotlincrypto.core.InternalKotlinCryptoApi
 import org.kotlincrypto.core.digest.Digest
 import org.kotlincrypto.core.digest.internal.DigestState
 import kotlin.random.Random
@@ -28,7 +27,6 @@ import kotlin.random.Random
 @Measurement(iterations = 5, time = 3)
 open class DigestBenchmark {
 
-    @OptIn(InternalKotlinCryptoApi::class)
     private class TestDigest: Digest {
         constructor(): super("Benchmark", 32, 32)
         private constructor(state: DigestState): super(state)

build.gradle.kts

@@ -53,7 +53,6 @@ apiValidation {
     if (CHECK_PUBLICATION) {
         ignoredProjects.add("check-publication")
     } else {
-        nonPublicMarkers.add("org.kotlincrypto.core.InternalKotlinCryptoApi")
         ignoredProjects.add("benchmarks")
     }
 }

library/core/api/core.api

@@ -22,3 +22,7 @@ public abstract interface class org/kotlincrypto/core/Updatable {
 	public abstract fun update ([BII)V
 }
 
+public final class org/kotlincrypto/core/_AndroidSdkIntKt {
+	public static final fun getKC_ANDROID_SDK_INT ()Ljava/lang/Integer;
+}
+

library/core/src/commonMain/kotlin/org/kotlincrypto/core/Algorithm.kt

@@ -15,9 +15,12 @@
  **/
 package org.kotlincrypto.core
 
-/**
- * Denotes a class as a user of a specified cryptographic [algorithm]
- * */
 public interface Algorithm {
+
+    /**
+     * Returns a string that identifies the algorithm, independent of
+     * implementation details. The name should be a standard Java Security
+     * name (such as "SHA-256").
+     * */
     public fun algorithm(): String
 }

library/core/src/commonMain/kotlin/org/kotlincrypto/core/Annotation.kt

@@ -23,7 +23,7 @@ package org.kotlincrypto.core
  *
  * Any usage of a declaration annotated with [ExperimentalKotlinCryptoApi]
  * must be accepted by annotating that usage with the [OptIn]
- * annotation, e.g @OptIn(ExperimentalKotlinCryptoApi::class), or by using
+ * annotation, e.g. @OptIn(ExperimentalKotlinCryptoApi::class), or by using
  * the following compiler argument:
  *
  *   -Xopt-in=org.kotlincrypto.core.ExperimentalKotlinCryptoApi
@@ -51,7 +51,7 @@ public annotation class ExperimentalKotlinCryptoApi
  *
  * Any usage of a declaration annotated with [InternalKotlinCryptoApi]
  * must be accepted by annotating that usage with the [OptIn]
- * annotation, e.g @OptIn(InternalKotlinCryptoApi::class), or by using
+ * annotation, e.g. @OptIn(InternalKotlinCryptoApi::class), or by using
  * the following compiler argument:
  *
  *   -Xopt-in=org.kotlincrypto.core.InternalKotlinCryptoApi

library/core/src/commonMain/kotlin/org/kotlincrypto/core/Copyable.kt

@@ -15,13 +15,11 @@
  **/
 package org.kotlincrypto.core
 
-/**
- * Denotes a class as being able to be copied such that
- * a new instance can be created.
- *
- * Classes with state should initialize new instances
- * with a copy of the current instance's state.
- * */
 public interface Copyable<out T: Any> {
+
+    /**
+     * Copies the instance and its state to a new instance that
+     * is wholly independent of the old instance.
+     * */
     public fun copy(): T
 }

library/core/src/commonMain/kotlin/org/kotlincrypto/core/Resettable.kt

@@ -15,9 +15,10 @@
  **/
 package org.kotlincrypto.core
 
-/**
- * Denotes a class as being able to be [reset]
- * */
 public interface Resettable {
+
+    /**
+     * Resets the instance for further use.
+     * */
     public fun reset()
 }

library/core/src/commonMain/kotlin/org/kotlincrypto/core/Updatable.kt

@@ -15,12 +15,33 @@
  **/
 package org.kotlincrypto.core
 
-/**
- * Denotes a class as being able to be [update]ed.
- * */
 public interface Updatable {
+
+    /**
+     * Updates the instance with the specified byte.
+     *
+     * @param [input] The byte to update the instance with.
+     * */
     public fun update(input: Byte)
+
+    /**
+     * Updates the instance with the specified array of bytes.
+     *
+     * @param [input] The array of bytes to update the instance with.
+     * */
     public fun update(input: ByteArray)
-    @Throws(IllegalArgumentException::class, IndexOutOfBoundsException::class)
+
+    /**
+     * Updates the instance with the specified array of bytes,
+     * starting at [offset]
+     *
+     * @param [input] The array of bytes to update the instance with.
+     * @param [offset] The index to start from in the array of bytes.
+     * @param [len] The number of bytes to use, starting at [offset].
+     * @throws [IllegalArgumentException] if [input] size is inappropriate
+     *   for given [len] parameter.
+     * @throws [IndexOutOfBoundsException] if [offset] and [len] are
+     *   inappropriate.
+     * */
     public fun update(input: ByteArray, offset: Int, len: Int)
 }

library/digest/api/digest.api

@@ -1,4 +1,6 @@
 public abstract class org/kotlincrypto/core/digest/Digest : java/security/MessageDigest, java/lang/Cloneable, org/kotlincrypto/core/Algorithm, org/kotlincrypto/core/Copyable, org/kotlincrypto/core/Resettable, org/kotlincrypto/core/Updatable {
+	protected fun <init> (Ljava/lang/String;II)V
+	protected fun <init> (Lorg/kotlincrypto/core/digest/internal/DigestState;)V
 	public final fun algorithm ()Ljava/lang/String;
 	public final fun blockSize ()I
 	public final fun clone ()Ljava/lang/Object;

library/digest/api/digest.klib.api

@@ -7,6 +7,9 @@
 
 // Library unique name: <org.kotlincrypto.core:digest>
 abstract class org.kotlincrypto.core.digest/Digest : org.kotlincrypto.core/Algorithm, org.kotlincrypto.core/Copyable<org.kotlincrypto.core.digest/Digest>, org.kotlincrypto.core/Resettable, org.kotlincrypto.core/Updatable { // org.kotlincrypto.core.digest/Digest|null[0]
+    constructor <init>(kotlin/String, kotlin/Int, kotlin/Int) // org.kotlincrypto.core.digest/Digest.<init>|<init>(kotlin.String;kotlin.Int;kotlin.Int){}[0]
+    constructor <init>(org.kotlincrypto.core.digest.internal/DigestState) // org.kotlincrypto.core.digest/Digest.<init>|<init>(org.kotlincrypto.core.digest.internal.DigestState){}[0]
+
     abstract fun compress(kotlin/ByteArray, kotlin/Int) // org.kotlincrypto.core.digest/Digest.compress|compress(kotlin.ByteArray;kotlin.Int){}[0]
     abstract fun copy(org.kotlincrypto.core.digest.internal/DigestState): org.kotlincrypto.core.digest/Digest // org.kotlincrypto.core.digest/Digest.copy|copy(org.kotlincrypto.core.digest.internal.DigestState){}[0]
     abstract fun digest(kotlin/Long, kotlin/Int, kotlin/ByteArray): kotlin/ByteArray // org.kotlincrypto.core.digest/Digest.digest|digest(kotlin.Long;kotlin.Int;kotlin.ByteArray){}[0]

library/digest/src/commonMain/kotlin/org/kotlincrypto/core/digest/Digest.kt

@@ -36,13 +36,15 @@ public expect abstract class Digest: Algorithm, Copyable<Digest>, Resettable, Up
     /**
      * Creates a new [Digest] for the specified parameters.
      *
+     * @param [algorithm] See [Algorithm.algorithm]
+     * @param [blockSize] See [Digest.blockSize]
+     * @param [digestLength] See [Digest.digestLength]
      * @throws [IllegalArgumentException] when:
      *  - [algorithm] is blank
      *  - [blockSize] is less than or equal to 0
      *  - [blockSize] is not a factor of 8
-     *  - [digestLength] is less than 0
+     *  - [digestLength] is negative
      * */
-    @InternalKotlinCryptoApi
     @Throws(IllegalArgumentException::class)
     protected constructor(algorithm: String, blockSize: Int, digestLength: Int)
 
@@ -53,51 +55,110 @@ public expect abstract class Digest: Algorithm, Copyable<Digest>, Resettable, Up
      * Implementors of [Digest] should have a private secondary constructor
      * that is utilized by its [copy] implementation.
      *
+     * e.g.
+     *
+     *     public class SHA256: Digest {
+     *
+     *         public constructor(): super("SHA-256", 64, 32) {
+     *             // Initialize...
+     *         }
+     *         private constructor(thiz: SHA256, state: DigestState): super(state) {
+     *             // Copy implementation details...
+     *         }
+     *         protected override fun copy(state: DigestState): Digest = SHA256(this, state)
+     *         // ...
+     *     }
+     *
      * @see [DigestState]
      * */
-    @InternalKotlinCryptoApi
     protected constructor(state: DigestState)
 
-    public final override fun algorithm(): String
+    /**
+     * The number of byte blocks (in factors of 8) that the implementation
+     * requires before one round of input processing is to occur. This value
+     * is also representative of the digest's buffer size, and will always
+     * be greater than 0.
+     * */
     public fun blockSize(): Int
+
+    /**
+     * The number of bytes the implementation returns when [digest] is called.
+     * */
     public fun digestLength(): Int
 
+    // See Algorithm interface documentation
+    public final override fun algorithm(): String
+
+    // See Updatable interface documentation
     public final override fun update(input: Byte)
+    // See Updatable interface documentation
     public final override fun update(input: ByteArray)
-    @Throws(IllegalArgumentException::class, IndexOutOfBoundsException::class)
+    // See Updatable interface documentation
     public final override fun update(input: ByteArray, offset: Int, len: Int)
 
+    /**
+     * Completes the computation, performing final operations and returning
+     * the resultant array of bytes. The [Digest] is [reset] afterward.
+     * */
     public fun digest(): ByteArray
+
+    /**
+     * Updates the instance with provided [input], then completes the computation,
+     * performing final operations and returning the resultant array of bytes. The
+     * [Digest] is [reset] afterward.
+     * */
     public fun digest(input: ByteArray): ByteArray
 
+    // See Resettable interface documentation
     public final override fun reset()
 
+    // See Copyable interface documentation
     public final override fun copy(): Digest
+
+    /**
+     * Called by the public [copy] function which produces the
+     * [DigestState] needed to create a wholly new instance.
+     * */
     protected abstract fun copy(state: DigestState): Digest
 
     /**
-     * Called whenever a full [blockSize] worth of bytes is available
-     * to be processed, starting at index [offset] for the [input].
+     * Called whenever a full [blockSize] worth of bytes are available for processing,
+     * starting at index [offset] for the provided [input]. Implementations **must not**
+     * alter [input].
      * */
     protected abstract fun compress(input: ByteArray, offset: Int)
+
+    /**
+     * Called to complete the computation, providing any input that may be
+     * buffered awaiting processing.
+     *
+     * @param [bitLength] The number of bits that have been processed, including
+     *   those remaining in the [buffer]
+     * @param [bufferOffset] The index at which the next input would be placed in
+     *   the [buffer]
+     * @param [buffer] Unprocessed input
+     * */
     protected abstract fun digest(bitLength: Long, bufferOffset: Int, buffer: ByteArray): ByteArray
-    protected abstract fun resetDigest()
 
     /**
-     * Protected, direct access to the [Digest]'s buffer. All external input
-     * is directed here such that implementations can override and intercept
-     * if necessary.
+     * Optional override for implementations to intercept cleansed input before
+     * being processed by the [Digest] abstraction.
      * */
     protected open fun updateDigest(input: Byte)
 
     /**
-     * Protected, direct access to the [Digest]'s buffer. All external input
-     * is validated before being directed here such that implementations can
-     * override and intercept if necessary.
+     * Optional override for implementations to intercept cleansed input before
+     * being processed by the [Digest] abstraction. Parameters passed to this
+     * function are always valid and have been checked for appropriateness.
      * */
     protected open fun updateDigest(input: ByteArray, offset: Int, len: Int)
 
+    protected abstract fun resetDigest()
+
+    /** @suppress */
     public final override fun equals(other: Any?): Boolean
+    /** @suppress */
     public final override fun hashCode(): Int
+    /** @suppress */
     public final override fun toString(): String
 }

library/digest/src/commonTest/kotlin/org/kotlincrypto/core/digest/TestDigest.kt

@@ -15,11 +15,8 @@
  **/
 package org.kotlincrypto.core.digest
 
-import org.kotlincrypto.core.InternalKotlinCryptoApi
 import org.kotlincrypto.core.digest.internal.DigestState
 
-@Suppress("UnnecessaryOptInAnnotation")
-@OptIn(InternalKotlinCryptoApi::class)
 class TestDigest: Digest {
 
     private val compress: (input: ByteArray, offset: Int) -> Unit