Improve KDoc comments for kmath-functions

kmath-functions/src/commonMain/kotlin/space/kscience/kmath/functions/Polynomial.kt

@@ -10,8 +10,9 @@ import kotlin.math.max
 import kotlin.math.pow
 
 /**
- * Polynomial coefficients without fixation on specific context they are applied to
- * @param coefficients constant is the leftmost coefficient
+ * Polynomial coefficients model without fixation on specific context they are applied to.
+ *
+ * @param coefficients constant is the leftmost coefficient.
  */
 public inline class Polynomial<T : Any>(public val coefficients: List<T>)
 
@@ -21,8 +22,14 @@ public inline class Polynomial<T : Any>(public val coefficients: List<T>)
 @Suppress("FunctionName")
 public fun <T : Any> Polynomial(vararg coefficients: T): Polynomial<T> = Polynomial(coefficients.toList())
 
+/**
+ * Evaluates the value of the given double polynomial for given double argument.
+ */
 public fun Polynomial<Double>.value(): Double = coefficients.reduceIndexed { index, acc, d -> acc + d.pow(index) }
 
+/**
+ * Evaluates the value of the given polynomial for given argument.
+ */
 public fun <T : Any, C : Ring<T>> Polynomial<T>.value(ring: C, arg: T): T = ring {
     if (coefficients.isEmpty()) return@ring zero
     var res = coefficients.first()
@@ -38,19 +45,23 @@ public fun <T : Any, C : Ring<T>> Polynomial<T>.value(ring: C, arg: T): T = ring
 }
 
 /**
- * Represent the polynomial as a regular context-less function
+ * Represent the polynomial as a regular context-less function.
  */
 public fun <T : Any, C : Ring<T>> Polynomial<T>.asFunction(ring: C): (T) -> T = { value(ring, it) }
 
 /**
- * An algebra for polynomials
+ * Space of polynomials.
+ *
+ * @param T the type of operated polynomials.
+ * @param C the intersection of [Ring] of [T] and [ScaleOperations] of [T].
+ * @param ring the [C] instance.
  */
 public class PolynomialSpace<T : Any, C>(
     private val ring: C,
 ) : Group<Polynomial<T>>, ScaleOperations<Polynomial<T>> where C : Ring<T>, C : ScaleOperations<T> {
     public override val zero: Polynomial<T> = Polynomial(emptyList())
 
-    override fun Polynomial<T>.unaryMinus(): Polynomial<T> = with(ring) {
+    override fun Polynomial<T>.unaryMinus(): Polynomial<T> = ring {
         Polynomial(coefficients.map { -it })
     }
 
@@ -67,6 +78,9 @@ public class PolynomialSpace<T : Any, C>(
     public override fun scale(a: Polynomial<T>, value: Double): Polynomial<T> =
         ring { Polynomial(List(a.coefficients.size) { index -> a.coefficients[index] * value }) }
 
+    /**
+     * Evaluates the polynomial for the given value [arg].
+     */
     public operator fun Polynomial<T>.invoke(arg: T): T = value(ring, arg)
 }
 

kmath-functions/src/commonMain/kotlin/space/kscience/kmath/integration/Integrator.kt

@@ -1,11 +1,11 @@
 package space.kscience.kmath.integration
 
 /**
- * A general interface for all integrators
+ * A general interface for all integrators.
  */
 public interface Integrator<I : Integrand> {
     /**
-     * Run one integration pass and return a new [Integrand] with a new set of features
+     * Runs one integration pass and return a new [Integrand] with a new set of features.
      */
     public fun integrate(integrand: I): I
-}
+}

kmath-functions/src/commonMain/kotlin/space/kscience/kmath/integration/UnivariateIntegrand.kt

@@ -61,4 +61,4 @@ public fun UnivariateIntegrator<Double>.integrate(
     return integrate(
         UnivariateIntegrand(function, *features.toTypedArray())
     ).value ?: error("Unexpected: no value after integration.")
-}
+}

kmath-functions/src/commonMain/kotlin/space/kscience/kmath/interpolation/SplineInterpolator.kt

@@ -8,8 +8,11 @@ import space.kscience.kmath.operations.invoke
 import space.kscience.kmath.structures.MutableBufferFactory
 
 /**
- * Generic spline interpolator. Not recommended for performance critical places, use platform-specific and type specific ones.
- * Based on https://github.com/apache/commons-math/blob/eb57d6d457002a0bb5336d789a3381a24599affe/src/main/java/org/apache/commons/math4/analysis/interpolation/SplineInterpolator.java
+ * Generic spline interpolator. Not recommended for performance critical places, use platform-specific and type
+ * specific ones.
+ *
+ * Based on
+ * https://github.com/apache/commons-math/blob/eb57d6d457002a0bb5336d789a3381a24599affe/src/main/java/org/apache/commons/math4/analysis/interpolation/SplineInterpolator.java
  */
 public class SplineInterpolator<T : Comparable<T>>(
     public override val algebra: Field<T>,

kmath-functions/src/commonMain/kotlin/space/kscience/kmath/interpolation/XYPointSet.kt

@@ -3,13 +3,40 @@ package space.kscience.kmath.interpolation
 import space.kscience.kmath.nd.Structure2D
 import space.kscience.kmath.structures.Buffer
 
+/**
+ * Pair of associated buffers for X and Y axes values.
+ *
+ * @param X the type of X values.
+ * @param Y the type of Y values.
+ */
 public interface XYPointSet<X, Y> {
+    /**
+     * The size of all the involved buffers.
+     */
     public val size: Int
+
+    /**
+     * The buffer of X values.
+     */
     public val x: Buffer<X>
+
+    /**
+     * The buffer of Y values.
+     */
     public val y: Buffer<Y>
 }
 
+/**
+ * Triple of associated buffers for X, Y, and Z axes values.
+ *
+ * @param X the type of X values.
+ * @param Y the type of Y values.
+ * @param Z the type of Z values.
+ */
 public interface XYZPointSet<X, Y, Z> : XYPointSet<X, Y> {
+    /**
+     * The buffer of Z values.
+     */
     public val z: Buffer<Z>
 }