Document and make more consistent buffers API

kmath-core/src/commonMain/kotlin/scientifik/kmath/structures/Buffers.kt

@@ -97,10 +97,13 @@ val Buffer<*>.indices: IntRange get() = 0 until size
  * A generic mutable random-access structure for both primitives and objects.
  */
 interface MutableBuffer<T> : Buffer<T> {
+    /**
+     * Sets the array element at the specified [index] to the specified [value].
+     */
     operator fun set(index: Int, value: T)
 
     /**
-     * A shallow copy of the buffer
+     * Returns a shallow copy of the buffer.
      */
     fun copy(): MutableBuffer<T>
 

kmath-core/src/commonMain/kotlin/scientifik/kmath/structures/IntBuffer.kt

@@ -21,6 +21,28 @@ inline class IntBuffer(val array: IntArray) : MutableBuffer<Int> {
 
 }
 
+/**
+ * Creates a new [IntBuffer] with the specified [size], where each element is calculated by calling the specified
+ * [init] function.
+ *
+ * The function [init] is called for each array element sequentially starting from the first one.
+ * It should return the value for an array element given its index.
+ */
+@Suppress("FunctionName")
+inline fun IntBuffer(size: Int, init: (Int) -> Int): IntBuffer = IntBuffer(IntArray(size) { init(it) })
+
+/**
+ * Returns a new [IntBuffer] of given elements.
+ */
+@Suppress("FunctionName")
+fun IntBuffer(vararg ints: Int): IntBuffer = IntBuffer(ints)
+
+/**
+ * Returns a [IntArray] containing all of the elements of this [MutableBuffer].
+ */
+val MutableBuffer<out Int>.array: IntArray
+    get() = (if (this is IntBuffer) array else IntArray(size) { get(it) })
+
 /**
  * Returns [IntBuffer] over this array.
  *

kmath-core/src/commonMain/kotlin/scientifik/kmath/structures/RealBuffer.kt

@@ -15,20 +15,32 @@ inline class RealBuffer(val array: DoubleArray) : MutableBuffer<Double> {
         RealBuffer(array.copyOf())
 }
 
+/**
+ * Creates a new array with the specified [size], where each element is calculated by calling the specified
+ * [init] function.
+ *
+ * The function [init] is called for each array element sequentially starting from the first one.
+ * It should return the value for an array element given its index.
+ */
 @Suppress("FunctionName")
 inline fun RealBuffer(size: Int, init: (Int) -> Double): RealBuffer = RealBuffer(DoubleArray(size) { init(it) })
 
+/**
+ * Returns a new [RealBuffer] of given elements.
+ */
 @Suppress("FunctionName")
 fun RealBuffer(vararg doubles: Double): RealBuffer = RealBuffer(doubles)
 
 /**
- * Transform buffer of doubles into array for high performance operations
+ * Returns a [DoubleArray] containing all of the elements of this [MutableBuffer].
  */
 val MutableBuffer<out Double>.array: DoubleArray
-    get() = if (this is RealBuffer) {
-        array
-    } else {
-        DoubleArray(size) { get(it) }
-    }
+    get() = (if (this is RealBuffer) array else DoubleArray(size) { get(it) })
 
+/**
+ * Returns [RealBuffer] over this array.
+ *
+ * @receiver the array.
+ * @return the new buffer.
+ */
 fun DoubleArray.asBuffer(): RealBuffer = RealBuffer(this)