From 3c2d05ead42dcb69d289c854135d0e1d0ed16e02 Mon Sep 17 00:00:00 2001
From: Kristoffer Paulsson <kristoffer.paulsson@talenten.se>
Date: Tue, 3 May 2022 15:52:48 +0200
Subject: [PATCH] Added missing documentation.

---
 .../org/angelos/io/buf/AbstractBuffer.kt      | 11 +++++
 .../org/angelos/io/buf/AbstractByteBuffer.kt  | 10 +++++
 .../io/buf/AbstractMutableByteBuffer.kt       | 10 +++++
 .../io/buf/AbstractMutableNativeByteBuffer.kt | 10 +++++
 .../io/buf/AbstractNativeByteBuffer.kt        | 10 +++++
 .../kotlin/org/angelos/io/buf/Buffer.kt       |  8 ++++
 .../kotlin/org/angelos/io/buf/ByteBuffer.kt   | 11 +++++
 .../kotlin/org/angelos/io/buf/Endianness.kt   | 40 +++++++++++++++++++
 .../kotlin/org/angelos/io/buf/Gettable.kt     |  5 +++
 .../org/angelos/io/buf/MutableByteBuffer.kt   | 11 +++++
 .../angelos/io/buf/MutableNativeByteBuffer.kt | 10 +++++
 .../org/angelos/io/buf/NativeByteBuffer.kt    | 10 +++++
 .../kotlin/org/angelos/io/buf/Settable.kt     |  5 +++
 .../kotlin/org/angelos/io/buf/BufferTest.kt   | 16 ++++++++
 .../org/angelos/io/buf/ByteBufferTest.kt      |  8 ++++
 .../org/angelos/io/buf/EndiannessTest.kt      | 27 +++++++++++++
 .../angelos/io/buf/MutableByteBufferTest.kt   |  8 ++++
 .../io/buf/MutableNativeByteBufferTest.kt     |  8 ++++
 .../angelos/io/buf/NativeByteBufferTest.kt    |  8 ++++
 .../org/angelos/io/buf/EndiannessTest.kt      |  5 +++
 .../org/angelos/io/buf/EndiannessTest.kt      |  4 ++
 .../org/angelos/io/buf/EndiannessTest.kt      |  4 ++
 22 files changed, 239 insertions(+)

diff --git a/buffer/src/commonMain/kotlin/org/angelos/io/buf/AbstractBuffer.kt b/buffer/src/commonMain/kotlin/org/angelos/io/buf/AbstractBuffer.kt
index a474135..99ad978 100644
--- a/buffer/src/commonMain/kotlin/org/angelos/io/buf/AbstractBuffer.kt
+++ b/buffer/src/commonMain/kotlin/org/angelos/io/buf/AbstractBuffer.kt
@@ -17,6 +17,17 @@ package org.angelos.io.buf
 import kotlin.math.absoluteValue
 import kotlin.math.min
 
+/**
+ * Abstract buffer from which all buffer implementations must inherit.
+ * Implements the basic logic regarding size, position and limit of reading and writing space.
+ *
+ * @constructor
+ *
+ * @param size max size of the buffer
+ * @param limit initial limit if partial data already exists
+ * @param position initial position in an already existing data stream
+ * @param endianness endian of the buffered data
+ */
 abstract class AbstractBuffer internal constructor(
     size: Int,
     limit: Int,
diff --git a/buffer/src/commonMain/kotlin/org/angelos/io/buf/AbstractByteBuffer.kt b/buffer/src/commonMain/kotlin/org/angelos/io/buf/AbstractByteBuffer.kt
index 886467e..5b07f8f 100644
--- a/buffer/src/commonMain/kotlin/org/angelos/io/buf/AbstractByteBuffer.kt
+++ b/buffer/src/commonMain/kotlin/org/angelos/io/buf/AbstractByteBuffer.kt
@@ -14,6 +14,16 @@
  */
 package org.angelos.io.buf
 
+/**
+ * Abstract byte buffer implements the read and endianness logic directly for use.
+ *
+ * @constructor
+ *
+ * @param size
+ * @param limit
+ * @param position
+ * @param endianness
+ */
 abstract class AbstractByteBuffer internal constructor(
     size: Int,
     limit: Int,
diff --git a/buffer/src/commonMain/kotlin/org/angelos/io/buf/AbstractMutableByteBuffer.kt b/buffer/src/commonMain/kotlin/org/angelos/io/buf/AbstractMutableByteBuffer.kt
index e300f95..9d0a98b 100644
--- a/buffer/src/commonMain/kotlin/org/angelos/io/buf/AbstractMutableByteBuffer.kt
+++ b/buffer/src/commonMain/kotlin/org/angelos/io/buf/AbstractMutableByteBuffer.kt
@@ -14,6 +14,16 @@
  */
 package org.angelos.io.buf
 
+/**
+ * Abstract mutable byte buffer implements the logic for write operations.
+ *
+ * @constructor
+ *
+ * @param size
+ * @param limit
+ * @param position
+ * @param endianness
+ */
 abstract class AbstractMutableByteBuffer internal constructor(
     size: Int,
     limit: Int,
diff --git a/buffer/src/commonMain/kotlin/org/angelos/io/buf/AbstractMutableNativeByteBuffer.kt b/buffer/src/commonMain/kotlin/org/angelos/io/buf/AbstractMutableNativeByteBuffer.kt
index 70fc339..3dd8b91 100644
--- a/buffer/src/commonMain/kotlin/org/angelos/io/buf/AbstractMutableNativeByteBuffer.kt
+++ b/buffer/src/commonMain/kotlin/org/angelos/io/buf/AbstractMutableNativeByteBuffer.kt
@@ -14,6 +14,16 @@
  */
 package org.angelos.io.buf
 
+/**
+ * Abstract mutable native byte buffer.
+ *
+ * @constructor
+ *
+ * @param size
+ * @param limit
+ * @param position
+ * @param endianness
+ */
 abstract class AbstractMutableNativeByteBuffer internal constructor(
     size: Int,
     limit: Int,
diff --git a/buffer/src/commonMain/kotlin/org/angelos/io/buf/AbstractNativeByteBuffer.kt b/buffer/src/commonMain/kotlin/org/angelos/io/buf/AbstractNativeByteBuffer.kt
index 553dc56..913c6f5 100644
--- a/buffer/src/commonMain/kotlin/org/angelos/io/buf/AbstractNativeByteBuffer.kt
+++ b/buffer/src/commonMain/kotlin/org/angelos/io/buf/AbstractNativeByteBuffer.kt
@@ -14,6 +14,16 @@
  */
 package org.angelos.io.buf
 
+/**
+ * Abstract native byte buffer.
+ *
+ * @constructor
+ *
+ * @param size
+ * @param limit
+ * @param position
+ * @param endianness
+ */
 abstract class AbstractNativeByteBuffer internal constructor(
     size: Int,
     limit: Int,
diff --git a/buffer/src/commonMain/kotlin/org/angelos/io/buf/Buffer.kt b/buffer/src/commonMain/kotlin/org/angelos/io/buf/Buffer.kt
index 63f5c66..2fdf4b2 100644
--- a/buffer/src/commonMain/kotlin/org/angelos/io/buf/Buffer.kt
+++ b/buffer/src/commonMain/kotlin/org/angelos/io/buf/Buffer.kt
@@ -85,6 +85,14 @@ interface Buffer: Gettable {
      */
     fun hasRemaining(size: Int) = hasRemaining(this, size)
 
+    /**
+     * Copy into a mutable buffer.
+     *
+     * @param destination destination mutable buffer to copy into
+     * @param destinationOffset offset where to start inside mutable buffer
+     * @param startIndex where to start copy from in source buffer
+     * @param endIndex when to stop copying from the source buffer
+     */
     fun copyInto(destination: MutableBuffer, destinationOffset: Int = 0, startIndex: Int = 0, endIndex: Int = size) {
         if (destination == this)
             throw IllegalArgumentException("It's not allowed for a buffer to copy into itself.")
diff --git a/buffer/src/commonMain/kotlin/org/angelos/io/buf/ByteBuffer.kt b/buffer/src/commonMain/kotlin/org/angelos/io/buf/ByteBuffer.kt
index 176f9c1..9afbaca 100644
--- a/buffer/src/commonMain/kotlin/org/angelos/io/buf/ByteBuffer.kt
+++ b/buffer/src/commonMain/kotlin/org/angelos/io/buf/ByteBuffer.kt
@@ -14,6 +14,17 @@
  */
 package org.angelos.io.buf
 
+/**
+ * Byte buffer implemented on the heap, as immutable.
+ *
+ * @constructor
+ *
+ * @param array ByteArray to wrap into a buffer
+ * @param size
+ * @param limit
+ * @param position
+ * @param endianness
+ */
 @Suppress("OVERRIDE_BY_INLINE")
 @OptIn(ExperimentalUnsignedTypes::class)
 class ByteBuffer internal constructor(
diff --git a/buffer/src/commonMain/kotlin/org/angelos/io/buf/Endianness.kt b/buffer/src/commonMain/kotlin/org/angelos/io/buf/Endianness.kt
index 51b9a0b..88503cc 100644
--- a/buffer/src/commonMain/kotlin/org/angelos/io/buf/Endianness.kt
+++ b/buffer/src/commonMain/kotlin/org/angelos/io/buf/Endianness.kt
@@ -14,14 +14,49 @@
  */
 package org.angelos.io.buf
 
+/**
+ * Representing endianness in systems and data buffers or streams.
+ *
+ * @property endian
+ * @constructor Create empty Endianness
+ */
 enum class Endianness(val endian: Boolean) {
+
+    /**
+     * Big endian enumeration value.
+     *
+     * @constructor Create empty Big Endian
+     */
     BIG_ENDIAN(false),
+
+    /**
+     * Little endian enumeration value.
+     *
+     * @constructor Create empty Little Endian
+     */
     LITTLE_ENDIAN(true);
 
+    /**
+     * Checks if the endianness is big.
+     *
+     * @return
+     */
     fun isBig(): Boolean = endian == BIG_ENDIAN.endian
+
+    /**
+     * Checks if the endianness is little.
+     *
+     * @return
+     */
     fun isLittle(): Boolean = endian == LITTLE_ENDIAN.endian
 
     companion object {
+
+        /**
+         * Native order of the running environment.
+         *
+         * @return the endian
+         */
         fun nativeOrder(): Endianness = when (Internals.getEndian()) {
             1 -> BIG_ENDIAN
             2 -> LITTLE_ENDIAN
@@ -29,6 +64,11 @@ enum class Endianness(val endian: Boolean) {
         }
     }
 
+    /**
+     * String representation of the endianness.
+     *
+     * @return human readable endianness
+     */
     override fun toString(): String = when (endian) {
         false -> "BIG_ENDIAN"
         true -> "LITTLE_ENDIAN"
diff --git a/buffer/src/commonMain/kotlin/org/angelos/io/buf/Gettable.kt b/buffer/src/commonMain/kotlin/org/angelos/io/buf/Gettable.kt
index 40cd40c..78d1eed 100644
--- a/buffer/src/commonMain/kotlin/org/angelos/io/buf/Gettable.kt
+++ b/buffer/src/commonMain/kotlin/org/angelos/io/buf/Gettable.kt
@@ -14,6 +14,11 @@
  */
 package org.angelos.io.buf
 
+/**
+ * Gettable interface to read data from a stream or buffer.
+ *
+ * @constructor Create empty Gettable
+ */
 interface Gettable {
     /**
      * Get next byte.
diff --git a/buffer/src/commonMain/kotlin/org/angelos/io/buf/MutableByteBuffer.kt b/buffer/src/commonMain/kotlin/org/angelos/io/buf/MutableByteBuffer.kt
index 62e83c8..b617b11 100644
--- a/buffer/src/commonMain/kotlin/org/angelos/io/buf/MutableByteBuffer.kt
+++ b/buffer/src/commonMain/kotlin/org/angelos/io/buf/MutableByteBuffer.kt
@@ -14,6 +14,17 @@
  */
 package org.angelos.io.buf
 
+/**
+ * Mutable byte buffer implemented on the heap, as mutable.
+ *
+ * @constructor
+ *
+ * @param array
+ * @param size
+ * @param limit
+ * @param position
+ * @param endianness
+ */
 @Suppress("OVERRIDE_BY_INLINE")
 @OptIn(ExperimentalUnsignedTypes::class)
 class MutableByteBuffer internal constructor(
diff --git a/buffer/src/commonMain/kotlin/org/angelos/io/buf/MutableNativeByteBuffer.kt b/buffer/src/commonMain/kotlin/org/angelos/io/buf/MutableNativeByteBuffer.kt
index 2bfa9c5..5560bff 100644
--- a/buffer/src/commonMain/kotlin/org/angelos/io/buf/MutableNativeByteBuffer.kt
+++ b/buffer/src/commonMain/kotlin/org/angelos/io/buf/MutableNativeByteBuffer.kt
@@ -14,6 +14,16 @@
  */
 package org.angelos.io.buf
 
+/**
+ * Mutable native byte buffer implemented outside save memory environment as mutable.
+ *
+ * @constructor
+ *
+ * @param size
+ * @param limit
+ * @param position
+ * @param endianness
+ */
 @Suppress("OVERRIDE_BY_INLINE")
 @OptIn(ExperimentalUnsignedTypes::class)
 class MutableNativeByteBuffer internal constructor(
diff --git a/buffer/src/commonMain/kotlin/org/angelos/io/buf/NativeByteBuffer.kt b/buffer/src/commonMain/kotlin/org/angelos/io/buf/NativeByteBuffer.kt
index 7820c35..aafb04b 100644
--- a/buffer/src/commonMain/kotlin/org/angelos/io/buf/NativeByteBuffer.kt
+++ b/buffer/src/commonMain/kotlin/org/angelos/io/buf/NativeByteBuffer.kt
@@ -14,6 +14,16 @@
  */
 package org.angelos.io.buf
 
+/**
+ * Native byte buffer implemented outside save memory environment as immutable.
+ *
+ * @constructor
+ *
+ * @param size
+ * @param limit
+ * @param position
+ * @param endianness
+ */
 @Suppress("OVERRIDE_BY_INLINE")
 @OptIn(ExperimentalUnsignedTypes::class)
 class NativeByteBuffer internal constructor(
diff --git a/buffer/src/commonMain/kotlin/org/angelos/io/buf/Settable.kt b/buffer/src/commonMain/kotlin/org/angelos/io/buf/Settable.kt
index d8c4253..7ad5768 100644
--- a/buffer/src/commonMain/kotlin/org/angelos/io/buf/Settable.kt
+++ b/buffer/src/commonMain/kotlin/org/angelos/io/buf/Settable.kt
@@ -14,6 +14,11 @@
  */
 package org.angelos.io.buf
 
+/**
+ * Settable interface to write data to a stream or buffer.
+ *
+ * @constructor Create empty Settable
+ */
 interface Settable {
     /**
      * Set next byte.
diff --git a/buffer/src/commonTest/kotlin/org/angelos/io/buf/BufferTest.kt b/buffer/src/commonTest/kotlin/org/angelos/io/buf/BufferTest.kt
index ae17caa..bd310c4 100644
--- a/buffer/src/commonTest/kotlin/org/angelos/io/buf/BufferTest.kt
+++ b/buffer/src/commonTest/kotlin/org/angelos/io/buf/BufferTest.kt
@@ -16,6 +16,11 @@ package org.angelos.io.buf
 
 import kotlin.test.assertEquals
 
+/**
+ * Containing tests for asserting and running all getNext*() and setNext*() methods in buffer implementations.
+ *
+ * @constructor Create empty Buffer test
+ */
 open class BufferTest {
     val refRead = byteArrayOf(
         0B1010101, 0B10101010u.toByte(),
@@ -68,6 +73,11 @@ open class BufferTest {
 
     val size: Int = refWrite.size
 
+    /**
+     * Read any buffer and make asserts on all getNext*() methods.
+     *
+     * @param buf
+     */
     fun readAny(buf: Buffer) {
         assertEquals(buf.getNextByte(), refByte)
         assertEquals(buf.getNextUByte(), refUByte)
@@ -83,6 +93,12 @@ open class BufferTest {
         }
     }
 
+    /**
+     * Write any buffer with data using all setNext*() methods.
+     * Verify by running the same buffer through readAny().
+     *
+     * @param buf
+     */
     fun writeAny(buf: MutableBuffer) {
         buf.setNextByte(refByte)
         buf.setNextUByte(refUByte)
diff --git a/buffer/src/commonTest/kotlin/org/angelos/io/buf/ByteBufferTest.kt b/buffer/src/commonTest/kotlin/org/angelos/io/buf/ByteBufferTest.kt
index f5a2f71..5b1313a 100644
--- a/buffer/src/commonTest/kotlin/org/angelos/io/buf/ByteBufferTest.kt
+++ b/buffer/src/commonTest/kotlin/org/angelos/io/buf/ByteBufferTest.kt
@@ -16,8 +16,16 @@ package org.angelos.io.buf
 
 import kotlin.test.Test
 
+/**
+ * Testing the ByteBuffer
+ *
+ * @constructor Create empty Byte buffer test
+ */
 class ByteBufferTest: BufferTest() {
 
+    /**
+     * Running tests on the ByteBuffer.
+     */
     @Test
     fun byteBuffer() {
         val buf = byteBufferOf(refRead.copyOf())
diff --git a/buffer/src/commonTest/kotlin/org/angelos/io/buf/EndiannessTest.kt b/buffer/src/commonTest/kotlin/org/angelos/io/buf/EndiannessTest.kt
index b96c756..dca215e 100644
--- a/buffer/src/commonTest/kotlin/org/angelos/io/buf/EndiannessTest.kt
+++ b/buffer/src/commonTest/kotlin/org/angelos/io/buf/EndiannessTest.kt
@@ -19,19 +19,37 @@ import kotlin.test.assertNotEquals
 import kotlin.test.assertNotNull
 import kotlin.test.assertTrue
 
+/**
+ * Containing common tests for Endianness.
+ *
+ * @constructor Create empty Abstract endian test
+ */
 open class AbstractEndianTest {
+
+    /**
+     * Running a test for isBig().
+     *
+     */
     @Test
     fun isBig() {
         val endianness = Endianness.BIG_ENDIAN
         assertTrue(endianness.isBig())
     }
 
+    /**
+     * Running a test for isLittle().
+     *
+     */
     @Test
     fun isLittle() {
         val endianness = Endianness.LITTLE_ENDIAN
         assertTrue(endianness.isLittle())
     }
 
+    /**
+     * Runing a test for toString().
+     *
+     */
     @Test
     fun testToString() {
         val endianness = Endianness.nativeOrder()
@@ -39,7 +57,16 @@ open class AbstractEndianTest {
     }
 }
 
+/**
+ * Running tests for Endianness.
+ *
+ * @constructor Create empty Endianness test
+ */
 expect class EndiannessTest : AbstractEndianTest {
+
+    /**
+     * Testing the native order compared to the real running environment.
+     */
     @Test
     fun nativeOrder()
 }
\ No newline at end of file
diff --git a/buffer/src/commonTest/kotlin/org/angelos/io/buf/MutableByteBufferTest.kt b/buffer/src/commonTest/kotlin/org/angelos/io/buf/MutableByteBufferTest.kt
index 2f1778c..87d5ab6 100644
--- a/buffer/src/commonTest/kotlin/org/angelos/io/buf/MutableByteBufferTest.kt
+++ b/buffer/src/commonTest/kotlin/org/angelos/io/buf/MutableByteBufferTest.kt
@@ -16,8 +16,16 @@ package org.angelos.io.buf
 
 import kotlin.test.Test
 
+/**
+ * Testing the MutableByteBuffer
+ *
+ * @constructor Create empty Mutable byte buffer test
+ */
 class MutableByteBufferTest : BufferTest() {
 
+    /**
+     * Running tests on the MutableByteBuffer.
+     */
     @Test
     fun mutableByteBuffer() {
         val buf = mutableByteBufferOf(refWrite.copyOf())
diff --git a/buffer/src/commonTest/kotlin/org/angelos/io/buf/MutableNativeByteBufferTest.kt b/buffer/src/commonTest/kotlin/org/angelos/io/buf/MutableNativeByteBufferTest.kt
index a3d8264..7c06716 100644
--- a/buffer/src/commonTest/kotlin/org/angelos/io/buf/MutableNativeByteBufferTest.kt
+++ b/buffer/src/commonTest/kotlin/org/angelos/io/buf/MutableNativeByteBufferTest.kt
@@ -16,8 +16,16 @@ package org.angelos.io.buf
 
 import kotlin.test.Test
 
+/**
+ * Testing the MutableNativeByteBuffer.
+ *
+ * @constructor Create empty Native byte buffer test
+ */
 class MutableNativeByteBufferTest: BufferTest() {
 
+    /**
+     * Running tests on the MutableNativeByteBuffer.
+     */
     @Test
     fun mutableNativeByteBuffer() {
         val buf = mutableNativeByteBufferOf(size)
diff --git a/buffer/src/commonTest/kotlin/org/angelos/io/buf/NativeByteBufferTest.kt b/buffer/src/commonTest/kotlin/org/angelos/io/buf/NativeByteBufferTest.kt
index d7ffc26..1f3b391 100644
--- a/buffer/src/commonTest/kotlin/org/angelos/io/buf/NativeByteBufferTest.kt
+++ b/buffer/src/commonTest/kotlin/org/angelos/io/buf/NativeByteBufferTest.kt
@@ -17,8 +17,16 @@ package org.angelos.io.buf
 import kotlin.test.Ignore
 import kotlin.test.Test
 
+/**
+ * Testing the NativeByteBuffer.
+ *
+ * @constructor Create empty Native byte buffer test
+ */
 class NativeByteBufferTest: BufferTest() {
 
+    /**
+     * Running tests on the NativeByteBuffer.
+     */
     @Ignore // There is no implemented way to enter data in an immutable native buffer.
     @Test
     fun nativeByteBuffer() {
diff --git a/buffer/src/jsTest/kotlin/org/angelos/io/buf/EndiannessTest.kt b/buffer/src/jsTest/kotlin/org/angelos/io/buf/EndiannessTest.kt
index b0917cb..324e7be 100644
--- a/buffer/src/jsTest/kotlin/org/angelos/io/buf/EndiannessTest.kt
+++ b/buffer/src/jsTest/kotlin/org/angelos/io/buf/EndiannessTest.kt
@@ -18,6 +18,11 @@ import kotlin.test.Test
 import kotlin.test.assertNotNull
 
 actual class EndiannessTest : AbstractEndianTest() {
+
+    /**
+     * Running tests for nativeOrder on JS never reaches the underlying system.
+     *
+     */
     @Test
     actual fun nativeOrder() {
         val endianness = Endianness.nativeOrder()
diff --git a/buffer/src/jvmTest/kotlin/org/angelos/io/buf/EndiannessTest.kt b/buffer/src/jvmTest/kotlin/org/angelos/io/buf/EndiannessTest.kt
index 04d3ce0..128a436 100644
--- a/buffer/src/jvmTest/kotlin/org/angelos/io/buf/EndiannessTest.kt
+++ b/buffer/src/jvmTest/kotlin/org/angelos/io/buf/EndiannessTest.kt
@@ -19,6 +19,10 @@ import kotlin.test.Test
 import kotlin.test.assertEquals
 
 actual class EndiannessTest : AbstractEndianTest() {
+
+    /**
+     * Running tests for nativeOrder on JVM checks against java.nio.ByteOrder for correctness.
+     */
     @Test
     actual fun nativeOrder() {
         when(Endianness.nativeOrder()) {
diff --git a/buffer/src/nativeTest/kotlin/org/angelos/io/buf/EndiannessTest.kt b/buffer/src/nativeTest/kotlin/org/angelos/io/buf/EndiannessTest.kt
index 6c14db7..9b3f094 100644
--- a/buffer/src/nativeTest/kotlin/org/angelos/io/buf/EndiannessTest.kt
+++ b/buffer/src/nativeTest/kotlin/org/angelos/io/buf/EndiannessTest.kt
@@ -19,6 +19,10 @@ import kotlin.test.Test
 import kotlin.test.assertEquals
 
 actual class EndiannessTest : AbstractEndianTest() {
+
+    /**
+     * Running tests for nativeOrder on Native checks against kotlin.native.Platform.isLittleEndian for correctness.
+     */
     @Test
     actual fun nativeOrder() {
         val endianness = Endianness.nativeOrder()