Unstable API annotation added + inconsistent docs fix + unnecessary BigIntField usage removed

benchmarks/src/jvmMain/kotlin/space/kscience/kmath/benchmarks/BigIntBenchmark.kt

@@ -10,16 +10,19 @@ import kotlinx.benchmark.Blackhole
 import org.openjdk.jmh.annotations.Benchmark
 import org.openjdk.jmh.annotations.Scope
 import org.openjdk.jmh.annotations.State
+import space.kscience.kmath.misc.UnstableKMathAPI
 import space.kscience.kmath.operations.*
+import java.math.BigInteger
 
 
+@UnstableKMathAPI
 @State(Scope.Benchmark)
 internal class BigIntBenchmark {
 
     val kmNumber = BigIntField.number(Int.MAX_VALUE)
     val jvmNumber = JBigIntegerField.number(Int.MAX_VALUE)
     val largeKmNumber = BigIntField { number(11).pow(100_000UL) }
-    val largeJvmNumber = JBigIntegerField { number(11).pow(100_000) }
+    val largeJvmNumber: BigInteger = JBigIntegerField { number(11).pow(100_000) }
     val bigExponent = 50_000
 
     @Benchmark

kmath-core/src/commonMain/kotlin/space/kscience/kmath/operations/Algebra.kt

@@ -6,6 +6,7 @@
 package space.kscience.kmath.operations
 
 import space.kscience.kmath.misc.Symbol
+import space.kscience.kmath.misc.UnstableKMathAPI
 
 /**
  * Stub for DSL the [Algebra] is.
@@ -247,11 +248,12 @@ public interface RingOperations<T> : GroupOperations<T> {
  */
 public interface Ring<T> : Group<T>, RingOperations<T> {
     /**
-     * neutral operation for multiplication
+     * The neutral element of multiplication
      */
     public val one: T
 }
 
+@UnstableKMathAPI
 public fun <T> Ring<T>.pow(base: T, exponent: ULong): T = when {
     this == zero && exponent > 0UL -> zero
     this == one -> base
@@ -259,6 +261,7 @@ public fun <T> Ring<T>.pow(base: T, exponent: ULong): T = when {
     else -> powWithoutOptimization(base, exponent)
 }
 
+@UnstableKMathAPI
 public fun <T> Ring<T>.pow(base: T, exponent: UInt): T = pow(base, exponent.toULong())
 
 private fun <T> Ring<T>.powWithoutOptimization(base: T, exponent: ULong): T = when (exponent) {

kmath-core/src/commonMain/kotlin/space/kscience/kmath/operations/BigInt.kt

@@ -98,7 +98,10 @@ public class BigInt internal constructor(
         else -> BigInt(sign, multiplyMagnitudeByUInt(magnitude, other))
     }
 
+    @UnstableKMathAPI
     public fun pow(other: ULong): BigInt = BigIntField { pow(this@BigInt, other) }
+
+    @UnstableKMathAPI
     public fun pow(other: UInt): BigInt = BigIntField { pow(this@BigInt, other) }
 
     public operator fun times(other: Int): BigInt = when {

kmath-core/src/commonMain/kotlin/space/kscience/kmath/operations/OptionalOperations.kt

@@ -147,7 +147,7 @@ public interface PowerOperations<T> : Algebra<T> {
 }
 
 /**
- * Raises this element to the power [pow].
+ * Raises this element to the power [power].
  *
  * @receiver the base.
  * @param power the exponent.

kmath-core/src/commonTest/kotlin/space/kscience/kmath/operations/BigIntAlgebraTest.kt

@@ -5,6 +5,7 @@
 
 package space.kscience.kmath.operations
 
+import space.kscience.kmath.misc.UnstableKMathAPI
 import space.kscience.kmath.testutils.RingVerifier
 import kotlin.math.pow
 import kotlin.test.Test
@@ -22,9 +23,9 @@ internal class BigIntAlgebraTest {
         assertEquals(res, 1_000_000.toBigInt())
     }
 
+    @UnstableKMathAPI
     @Test
     fun testKBigIntegerRingPow() {
-        BigIntField {
         for (num in -5..5)
             for (exponent in 0U..10U) {
                 assertEquals(
@@ -39,7 +40,6 @@ internal class BigIntAlgebraTest {
                 )
             }
     }
-    }
 
     @Test
     fun testKBigIntegerRingSum_100_000_000__100_000_000() {