Update algebra extensions, improve docs

kmath-core/src/commonMain/kotlin/scientifik/kmath/operations/AlgebraExtensions.kt

@@ -1,15 +1,62 @@
 package scientifik.kmath.operations
 
+/**
+ * Returns the sum of all elements in the iterable in this [Space].
+ *
+ * @receiver the algebra that provides addition.
+ * @param data the collection to sum up.
+ * @return the sum.
+ */
 fun <T> Space<T>.sum(data: Iterable<T>): T = data.fold(zero) { left, right -> add(left, right) }
+
+/**
+ * Returns the sum of all elements in the sequence in this [Space].
+ *
+ * @receiver the algebra that provides addition.
+ * @param data the collection to sum up.
+ * @return the sum.
+ */
 fun <T> Space<T>.sum(data: Sequence<T>): T = data.fold(zero) { left, right -> add(left, right) }
 
+/**
+ * Returns the sum of all elements in the iterable in provided space.
+ *
+ * @receiver the collection to sum up.
+ * @param space the algebra that provides addition.
+ * @return the sum.
+ */
 fun <T : Any, S : Space<T>> Iterable<T>.sumWith(space: S): T = space.sum(this)
 
 //TODO optimized power operation
-fun <T> RingOperations<T>.power(arg: T, power: Int): T {
+
+/**
+ * Raises [arg] to the natural power [power].
+ *
+ * @receiver the algebra to provide multiplication.
+ * @param arg the base.
+ * @param power the exponent.
+ * @return the base raised to the power.
+ */
+fun <T> Ring<T>.power(arg: T, power: Int): T {
+    require(power >= 0) { "The power can't be negative." }
+    require(power != 0 || arg != zero) { "The $zero raised to $power is not defined." }
+    if (power == 0) return one
     var res = arg
-    repeat(power - 1) {
-        res *= arg
-    }
+    repeat(power - 1) { res *= arg }
     return res
 }
+
+/**
+ * Raises [arg] to the integer power [power].
+ *
+ * @receiver the algebra to provide multiplication and division.
+ * @param arg the base.
+ * @param power the exponent.
+ * @return the base raised to the power.
+ */
+fun <T> Field<T>.power(arg: T, power: Int): T {
+    require(power != 0 || arg != zero) { "The $zero raised to $power is not defined." }
+    if (power == 0) return one
+    if (power < 0) return one / (this as Ring<T>).power(arg, -power)
+    return (this as Ring<T>).power(arg, power)
+}

kmath-core/src/commonMain/kotlin/scientifik/kmath/operations/OptionalOperations.kt

@@ -143,7 +143,11 @@ interface PowerOperations<T> : Algebra<T> {
 }
 
 /**
- * Raises [arg] to the power [pow].
+ * Raises this element to the power [pow].
+ *
+ * @receiver the base.
+ * @param power the exponent.
+ * @return the base raised to the power.
  */
 infix fun <T : MathElement<out PowerOperations<T>>> T.pow(power: Double): T = context.power(this, power)
 

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

@@ -4,13 +4,22 @@ import scientifik.kmath.operations.Complex
 import scientifik.kmath.operations.complex
 import kotlin.reflect.KClass
 
-
+/**
+ * Function that produces [Buffer] from its size and function that supplies values.
+ *
+ * @param T the type of buffer.
+ */
 typealias BufferFactory<T> = (Int, (Int) -> T) -> Buffer<T>
-typealias MutableBufferFactory<T> = (Int, (Int) -> T) -> MutableBuffer<T>
-
 
 /**
- * A generic random access structure for both primitives and objects
+ * Function that produces [MutableBuffer] from its size and function that supplies values.
+ *
+ * @param T the type of buffer.
+ */
+typealias MutableBufferFactory<T> = (Int, (Int) -> T) -> MutableBuffer<T>
+
+/**
+ * A generic random-access structure for both primitives and objects.
  */
 interface Buffer<T> {
 
@@ -69,12 +78,24 @@ interface Buffer<T> {
     }
 }
 
+/**
+ * Creates a sequence that returns all elements from this [Buffer].
+ */
 fun <T> Buffer<T>.asSequence(): Sequence<T> = Sequence(::iterator)
 
+/**
+ * Creates an iterable that returns all elements from this [Buffer].
+ */
 fun <T> Buffer<T>.asIterable(): Iterable<T> = Iterable(::iterator)
 
-val Buffer<*>.indices: IntRange get() = IntRange(0, size - 1)
+/**
+ * Returns an [IntRange] of the valid indices for this [Buffer].
+ */
+val Buffer<*>.indices: IntRange get() = 0 until size
 
+/**
+ * A generic mutable random-access structure for both primitives and objects.
+ */
 interface MutableBuffer<T> : Buffer<T> {
     operator fun set(index: Int, value: T)
 

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

@@ -1,5 +1,10 @@
 package scientifik.kmath.structures
 
+/**
+ * Specialized [MutableBuffer] implementation over [IntArray].
+ *
+ * @property array the underlying array.
+ */
 inline class IntBuffer(val array: IntArray) : MutableBuffer<Int> {
     override val size: Int get() = array.size
 
@@ -16,4 +21,10 @@ inline class IntBuffer(val array: IntArray) : MutableBuffer<Int> {
 
 }
 
+/**
+ * Returns [IntBuffer] over this array.
+ *
+ * @receiver the array.
+ * @return the new buffer.
+ */
 fun IntArray.asBuffer(): IntBuffer = IntBuffer(this)

kmath-core/src/jvmMain/kotlin/scientifik/kmath/operations/BigNumbers.kt

@@ -5,7 +5,7 @@ import java.math.BigInteger
 import java.math.MathContext
 
 /**
- * A field wrapper for Java [BigInteger]
+ * A field over [BigInteger].
  */
 object JBigIntegerField : Field<BigInteger> {
     override val zero: BigInteger
@@ -24,7 +24,9 @@ object JBigIntegerField : Field<BigInteger> {
 }
 
 /**
- * A Field wrapper for Java [BigDecimal]
+ * An abstract field over [BigDecimal].
+ *
+ * @property mathContext the [MathContext] to use.
  */
 abstract class JBigDecimalFieldBase internal constructor(val mathContext: MathContext = MathContext.DECIMAL64) :
     Field<BigDecimal>,
@@ -50,6 +52,9 @@ abstract class JBigDecimalFieldBase internal constructor(val mathContext: MathCo
 
 }
 
+/**
+ * A field over [BigDecimal].
+ */
 class JBigDecimalField(mathContext: MathContext = MathContext.DECIMAL64) : JBigDecimalFieldBase(mathContext) {
     companion object : JBigDecimalFieldBase()
 }