From dbb48a2a9f3ecabc0eb0aeb7e7c72d589aba0c4f Mon Sep 17 00:00:00 2001
From: Gleb Minaev <43728100+lounres@users.noreply.github.com>
Date: Mon, 13 Jun 2022 01:41:04 +0300
Subject: [PATCH] Added docstrings to ListPolynomial and ListRationalFunction
 fabric functions.

---
 .../kmath/functions/listConstructors.kt       | 56 +++++++++++++++----
 1 file changed, 44 insertions(+), 12 deletions(-)

diff --git a/kmath-functions/src/commonMain/kotlin/space/kscience/kmath/functions/listConstructors.kt b/kmath-functions/src/commonMain/kotlin/space/kscience/kmath/functions/listConstructors.kt
index fc55ba310..35c736914 100644
--- a/kmath-functions/src/commonMain/kotlin/space/kscience/kmath/functions/listConstructors.kt
+++ b/kmath-functions/src/commonMain/kotlin/space/kscience/kmath/functions/listConstructors.kt
@@ -14,52 +14,84 @@ import space.kscience.kmath.operations.Ring
 
 
 /**
- * Returns a [ListPolynomial] instance with given [coefficients]. The collection of coefficients will be reversed if
- * [reverse] parameter is true.
+ * Constructs a [ListPolynomial] instance with provided [coefficients]. The collection of coefficients will be reversed
+ * if [reverse] parameter is true.
  */
 @Suppress("FunctionName")
 public fun <C> ListPolynomial(coefficients: List<C>, reverse: Boolean = false): ListPolynomial<C> =
     ListPolynomial(with(coefficients) { if (reverse) reversed() else this })
 
 /**
- * Returns a [ListPolynomial] instance with given [coefficients]. The collection of coefficients will be reversed if
- * [reverse] parameter is true.
+ * Constructs a [ListPolynomial] instance with provided [coefficients]. The collection of coefficients will be reversed
+ * if [reverse] parameter is true.
  */
 @Suppress("FunctionName")
 public fun <C> ListPolynomial(vararg coefficients: C, reverse: Boolean = false): ListPolynomial<C> =
     ListPolynomial(with(coefficients) { if (reverse) reversed() else toList() })
 
+/**
+ * Represents [this] constant as a [ListPolynomial].
+ */
 public fun <C> C.asListPolynomial() : ListPolynomial<C> = ListPolynomial(listOf(this))
 
 
 // Waiting for context receivers :( FIXME: Replace with context receivers when they will be available
 
+/**
+ * Constructs [ListRationalFunction] instance with numerator and denominator constructed with provided
+ * [numeratorCoefficients] and [denominatorCoefficients]. The both collections of coefficients will be reversed if
+ * [reverse] parameter is true.
+ */
 @Suppress("FunctionName")
 public fun <C> ListRationalFunction(numeratorCoefficients: List<C>, denominatorCoefficients: List<C>, reverse: Boolean = false): ListRationalFunction<C> =
     ListRationalFunction<C>(
         ListPolynomial( with(numeratorCoefficients) { if (reverse) reversed() else this } ),
         ListPolynomial( with(denominatorCoefficients) { if (reverse) reversed() else this } )
     )
-@Suppress("FunctionName")
-public fun <C, A: Ring<C>> ListRationalFunctionSpace<C, A>.ListRationalFunction(numerator: ListPolynomial<C>): ListRationalFunction<C> =
-    ListRationalFunction<C>(numerator, polynomialOne)
+/**
+ * Constructs [ListRationalFunction] instance with provided [numerator] and unit denominator.
+ */
 @Suppress("FunctionName")
 public fun <C, A: Ring<C>> A.ListRationalFunction(numerator: ListPolynomial<C>): ListRationalFunction<C> =
     ListRationalFunction<C>(numerator, ListPolynomial(listOf(one)))
+/**
+ * Constructs [ListRationalFunction] instance with provided [numerator] and unit denominator.
+ */
 @Suppress("FunctionName")
-public fun <C, A: Ring<C>> ListRationalFunctionSpace<C, A>.ListRationalFunction(numeratorCoefficients: List<C>, reverse: Boolean = false): ListRationalFunction<C> =
-    ListRationalFunction<C>(
-        ListPolynomial( with(numeratorCoefficients) { if (reverse) reversed() else this } ),
-        polynomialOne
-    )
+public fun <C, A: Ring<C>> ListRationalFunctionSpace<C, A>.ListRationalFunction(numerator: ListPolynomial<C>): ListRationalFunction<C> =
+    ListRationalFunction<C>(numerator, polynomialOne)
+/**
+ * Constructs [ListRationalFunction] instance with numerator constructed with provided [numeratorCoefficients] and unit
+ * denominator. The collection of numerator coefficients will be reversed if [reverse] parameter is true.
+ */
 @Suppress("FunctionName")
 public fun <C, A: Ring<C>> A.ListRationalFunction(numeratorCoefficients: List<C>, reverse: Boolean = false): ListRationalFunction<C> =
     ListRationalFunction<C>(
         ListPolynomial( with(numeratorCoefficients) { if (reverse) reversed() else this } ),
         ListPolynomial(listOf(one))
     )
+/**
+ * Constructs [ListRationalFunction] instance with numerator constructed with provided [numeratorCoefficients] and unit
+ * denominator. The collection of numerator coefficients will be reversed if [reverse] parameter is true.
+ */
+@Suppress("FunctionName")
+public fun <C, A: Ring<C>> ListRationalFunctionSpace<C, A>.ListRationalFunction(numeratorCoefficients: List<C>, reverse: Boolean = false): ListRationalFunction<C> =
+    ListRationalFunction<C>(
+        ListPolynomial( with(numeratorCoefficients) { if (reverse) reversed() else this } ),
+        polynomialOne
+    )
 
+/**
+ * Represents [this] constant as a rational function.
+ */ // FIXME: When context receivers will be ready, delete this function and uncomment the following two
+public fun <C, A: Ring<C>> C.asListRationalFunction(ring: A) : ListRationalFunction<C> = ring.ListRationalFunction(asListPolynomial())
+///**
+// * Represents [this] constant as a rational function.
+// */
 //context(A)
 //public fun <C, A: Ring<C>> C.asListRationalFunction() : ListRationalFunction<C> = ListRationalFunction(asListPolynomial())
+///**
+// * Represents [this] constant as a rational function.
+// */
 //context(ListRationalFunctionSpace<C, A>)
 //public fun <C, A: Ring<C>> C.asListRationalFunction() : ListRationalFunction<C> = ListRationalFunction(asListPolynomial())
\ No newline at end of file