From 8367e13057fb19df3b6c356f6d5846bb92ffc6bd Mon Sep 17 00:00:00 2001
From: Iaroslav Postovalov <postovalovya@gmail.com>
Date: Wed, 5 Aug 2020 18:41:58 +0700
Subject: [PATCH] Improve documentation of complex and memoryspec

---
 .../scientifik/kmath/operations/Complex.kt    | 57 ++++++++++++++++---
 .../kotlin/scientifik/memory/MemorySpec.kt    | 29 ++++++----
 2 files changed, 67 insertions(+), 19 deletions(-)

diff --git a/kmath-core/src/commonMain/kotlin/scientifik/kmath/operations/Complex.kt b/kmath-core/src/commonMain/kotlin/scientifik/kmath/operations/Complex.kt
index ffd6c8dec..0ce144a33 100644
--- a/kmath-core/src/commonMain/kotlin/scientifik/kmath/operations/Complex.kt
+++ b/kmath-core/src/commonMain/kotlin/scientifik/kmath/operations/Complex.kt
@@ -11,13 +11,16 @@ import kotlin.math.*
 private val PI_DIV_2 = Complex(PI / 2, 0)
 
 /**
- * A field for complex numbers
+ * A field of [Complex].
  */
 object ComplexField : ExtendedField<Complex> {
     override val zero: Complex = Complex(0.0, 0.0)
 
     override val one: Complex = Complex(1.0, 0.0)
 
+    /**
+     * The imaginary unit.
+     */
     val i: Complex = Complex(0.0, 1.0)
 
     override fun add(a: Complex, b: Complex): Complex = Complex(a.re + b.re, a.im + b.im)
@@ -45,25 +48,59 @@ object ComplexField : ExtendedField<Complex> {
 
     override fun ln(arg: Complex): Complex = ln(arg.r) + i * atan2(arg.im, arg.re)
 
+    /**
+     * Adds complex number to real one.
+     *
+     * @receiver the addend.
+     * @param c the augend.
+     * @return the sum.
+     */
     operator fun Double.plus(c: Complex): Complex = add(this.toComplex(), c)
 
+    /**
+     * Subtracts complex number from real one.
+     *
+     * @receiver the minuend.
+     * @param c the subtrahend.
+     * @return the difference.
+     */
     operator fun Double.minus(c: Complex): Complex = add(this.toComplex(), -c)
 
+    /**
+     * Adds real number to complex one.
+     *
+     * @receiver the addend.
+     * @param d the augend.
+     * @return the sum.
+     */
     operator fun Complex.plus(d: Double): Complex = d + this
 
+    /**
+     * Subtracts real number from complex one.
+     *
+     * @receiver the minuend.
+     * @param d the subtrahend.
+     * @return the difference.
+     */
     operator fun Complex.minus(d: Double): Complex = add(this, -d.toComplex())
 
+    /**
+     * Multiplies real number by complex one.
+     *
+     * @receiver the multiplier.
+     * @param c the multiplicand.
+     * @receiver the product.
+     */
     operator fun Double.times(c: Complex): Complex = Complex(c.re * this, c.im * this)
 
-    override fun symbol(value: String): Complex = if (value == "i") {
-        i
-    } else {
-        super.symbol(value)
-    }
+    override fun symbol(value: String): Complex = if (value == "i") i else super.symbol(value)
 }
 
 /**
- * Complex number class
+ * Represents complex number.
+ *
+ * @property re The real part.
+ * @property im The imaginary part.
  */
 data class Complex(val re: Double, val im: Double) : FieldElement<Complex, Complex, ComplexField>, Comparable<Complex> {
     constructor(re: Number, im: Number) : this(re.toDouble(), im.toDouble())
@@ -104,6 +141,12 @@ val Complex.r: Double get() = sqrt(re * re + im * im)
  */
 val Complex.theta: Double get() = atan(im / re)
 
+/**
+ * Creates a complex number with real part equal to this real.
+ *
+ * @receiver the real part.
+ * @return the new complex number.
+ */
 fun Double.toComplex(): Complex = Complex(this, 0.0)
 
 inline fun Buffer.Companion.complex(size: Int, crossinline init: (Int) -> Complex): Buffer<Complex> {
diff --git a/kmath-memory/src/commonMain/kotlin/scientifik/memory/MemorySpec.kt b/kmath-memory/src/commonMain/kotlin/scientifik/memory/MemorySpec.kt
index 7999aa2ab..4d0035d09 100644
--- a/kmath-memory/src/commonMain/kotlin/scientifik/memory/MemorySpec.kt
+++ b/kmath-memory/src/commonMain/kotlin/scientifik/memory/MemorySpec.kt
@@ -1,7 +1,9 @@
 package scientifik.memory
 
 /**
- * A specification to read or write custom objects with fixed size in bytes
+ * A specification to read or write custom objects with fixed size in bytes.
+ *
+ * @param T the type of object this spec manages.
  */
 interface MemorySpec<T : Any> {
     /**
@@ -9,27 +11,30 @@ interface MemorySpec<T : Any> {
      */
     val objectSize: Int
 
+    /**
+     * Reads the object starting from [offset].
+     */
     fun MemoryReader.read(offset: Int): T
-    //TODO consider thread safety
+
+    // TODO consider thread safety
+
+    /**
+     * Writes the object [value] starting from [offset].
+     */
     fun MemoryWriter.write(offset: Int, value: T)
 }
 
-fun <T : Any> MemoryReader.read(spec: MemorySpec<T>, offset: Int): T = spec.run { read(offset) }
-fun <T : Any> MemoryWriter.write(spec: MemorySpec<T>, offset: Int, value: T) = spec.run { write(offset, value) }
+fun <T : Any> MemoryReader.read(spec: MemorySpec<T>, offset: Int): T = with(spec) { read(offset) }
+fun <T : Any> MemoryWriter.write(spec: MemorySpec<T>, offset: Int, value: T): Unit = with(spec) { write(offset, value) }
 
-inline fun <reified T : Any> MemoryReader.readArray(spec: MemorySpec<T>, offset: Int, size: Int) =
+inline fun <reified T : Any> MemoryReader.readArray(spec: MemorySpec<T>, offset: Int, size: Int): Array<T> =
     Array(size) { i ->
         spec.run {
             read(offset + i * objectSize)
         }
     }
 
-fun <T : Any> MemoryWriter.writeArray(spec: MemorySpec<T>, offset: Int, array: Array<T>) {
-    spec.run {
-        for (i in array.indices) {
-            write(offset + i * objectSize, array[i])
-        }
-    }
-}
+fun <T : Any> MemoryWriter.writeArray(spec: MemorySpec<T>, offset: Int, array: Array<T>): Unit =
+    with(spec) { array.indices.forEach { i -> write(offset + i * objectSize, array[i]) } }
 
 //TODO It is possible to add elastic MemorySpec with unknown object size
\ No newline at end of file