fixing some review issues

Jolanrensen · Jolanrensen · commit e6ab95b2be2e · 2023-03-27T13:01:35.000+02:00
diff --git a/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/ColumnsSelectionDsl.kt b/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/ColumnsSelectionDsl.kt
@@ -24,14 +24,14 @@ import kotlin.reflect.typeOf
 /**
  * Referring to a column in the selection DSL can be done in several ways corresponding to all
  * [Access APIs][AccessApi]:
- * TODO
+ * TODO: [Issue #286](https://github.com/Kotlin/dataframe/issues/286)
  */
 private interface CommonColumnSelectionExamples
 
 /** [Column Selection DSL][ColumnSelectionDsl] */
 internal interface ColumnSelectionDslLink
 
-/** TODO: Put examples and explanations here */
+/** TODO: [Issue #286](https://github.com/Kotlin/dataframe/issues/286) */
 public interface ColumnSelectionDsl<out T> : ColumnsContainer<T> {
 
     public operator fun <C> ColumnReference<C>.invoke(): DataColumn<C> = get(this)
@@ -50,7 +50,7 @@ public interface ColumnSelectionDsl<out T> : ColumnsContainer<T> {
 /** [Columns Selection DSL][ColumnsSelectionDsl] */
 internal interface ColumnsSelectionDslLink
 
-/** TODO: Put examples and explanations here */
+/** TODO: [Issue #286](https://github.com/Kotlin/dataframe/issues/286) */
 public interface ColumnsSelectionDsl<out T> : ColumnSelectionDsl<T>, SingleColumn<DataRow<T>> {
 
     public fun <C> ColumnSet<C>.first(condition: ColumnFilter<C>): SingleColumn<C> =
diff --git a/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/Nulls.kt b/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/Nulls.kt
diff --git a/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/update.kt b/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/update.kt
@@ -217,7 +217,7 @@ public fun <T, C> DataFrame<T>.update(vararg columns: ColumnReference<C>): Updat
     update { columns.toColumns() }
 
 /**
- * TODO this will be deprecated
+ * TODO this will be deprecated [PR #286](https://github.com/Kotlin/dataframe/pull/320)
  */
 public fun <T, C> DataFrame<T>.update(columns: Iterable<ColumnReference<C>>): Update<T, C> =
     update { columns.toColumnSet() }
diff --git a/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/AccessApi.kt b/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/AccessApi.kt
@@ -135,4 +135,4 @@ internal interface AccessApi {
 }
 
 /** [Access API][AccessApi] */
-internal interface AccessApiLink
+public const val AccessApiLink: Int = 0
diff --git a/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/ExpressionsGivenRow.kt b/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/ExpressionsGivenRow.kt
@@ -20,14 +20,14 @@ import org.jetbrains.kotlinx.dataframe.RowValueExpression as DfRowValueExpressio
  * for instance in [update.with][Update.with], and [convert.notNull][Convert.notNull]
  * (using [RowValueExpression][DfRowValueExpression]).
  *
- * Note:
+ * NOTE:
  *
  * [update with][org.jetbrains.kotlinx.dataframe.api.Update.with]- and [add][org.jetbrains.kotlinx.dataframe.api.add]-like expressions use [AddDataRow][org.jetbrains.kotlinx.dataframe.api.AddDataRow] instead of [DataRow][org.jetbrains.kotlinx.dataframe.DataRow] as the DSL's receiver type.
  * This is an extension to [RowValueExpression][org.jetbrains.kotlinx.dataframe.RowValueExpression] and
  * [RowExpression][org.jetbrains.kotlinx.dataframe.RowExpression] that provides access to
  * the modified/generated value of the preceding row ([AddDataRow.newValue][org.jetbrains.kotlinx.dataframe.api.AddDataRow.newValue]).
  *
- * A Row Expression is similar to a [Row Condition][org.jetbrains.kotlinx.dataframe.documentation.SelectingRows] but that expects a [Boolean][Boolean] as result.
+ * A [Row Expression][org.jetbrains.kotlinx.dataframe.documentation.ExpressionsGivenRow.RowExpression.WithExample] is similar to a [Row Condition][org.jetbrains.kotlinx.dataframe.documentation.SelectingRows] but that expects a [Boolean][Boolean] as result.
  */
 internal interface ExpressionsGivenRow {
 
diff --git a/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/NA.kt b/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/NA.kt
@@ -0,0 +1,18 @@
+package org.jetbrains.kotlinx.dataframe.documentation
+
+import org.jetbrains.kotlinx.dataframe.api.dropNA
+import org.jetbrains.kotlinx.dataframe.api.fillNA
+
+/**
+ * ## `NA`
+ * `NA` in Dataframe can be seen as "[NaN] or `null`".
+ *
+ * [Floats][Float] or [Doubles][Double] can be represented as [Float.NaN] or [Double.NaN], respectively,
+ * in cases where a mathematical operation is undefined, such as dividing by zero.
+ *
+ * You can also use [fillNA][fillNA] to replace `NAs` in certain columns with a given value or expression
+ * or [dropNA][dropNA] to drop rows with `NAs` in them.
+ *
+ * @see NaN
+ */
+internal interface NA
diff --git a/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/NaN.kt b/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/NaN.kt
@@ -0,0 +1,16 @@
+package org.jetbrains.kotlinx.dataframe.documentation
+
+import org.jetbrains.kotlinx.dataframe.api.dropNaNs
+import org.jetbrains.kotlinx.dataframe.api.fillNaNs
+
+/**
+ * ## `NaN`
+ * [Floats][Float] or [Doubles][Double] can be represented as [Float.NaN] or [Double.NaN], respectively,
+ * in cases where a mathematical operation is undefined, such as dividing by zero.
+ *
+ * You can also use [fillNaNs][fillNaNs] to replace `NaNs` in certain columns with a given value or expression
+ * or [dropNaNs][dropNaNs] to drop rows with `NaNs` in them.
+ *
+ * @see NA
+ */
+internal interface NaN
diff --git a/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/SelectingColumns.kt b/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/SelectingColumns.kt
@@ -10,12 +10,6 @@ import org.jetbrains.kotlinx.dataframe.columns.SingleColumn
 import org.jetbrains.kotlinx.dataframe.documentation.SelectingColumns.*
 import kotlin.reflect.KProperty
 
-/** {@comment
- * In this file we provide documentation for high-level operations such as
- * the operation of selecting columns.
- * }
- */
-
 /** [Selecting Columns][SelectingColumns] */
 internal interface SelectingColumnsLink
 
diff --git a/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/SelectingRows.kt b/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/SelectingRows.kt
@@ -1,7 +1,11 @@
 package org.jetbrains.kotlinx.dataframe.documentation
 
-import org.jetbrains.kotlinx.dataframe.*
+import org.jetbrains.kotlinx.dataframe.RowFilter
+import org.jetbrains.kotlinx.dataframe.RowValueFilter
 import org.jetbrains.kotlinx.dataframe.api.*
+import org.jetbrains.kotlinx.dataframe.documentation.SelectingRows.RowConditionLink
+import org.jetbrains.kotlinx.dataframe.documentation.SelectingRows.RowValueConditionLink
+import org.jetbrains.kotlinx.dataframe.index
 
 /**
  * ## Selecting Rows
@@ -14,7 +18,6 @@ import org.jetbrains.kotlinx.dataframe.api.*
  * (using [RowValueFilter]).
  *
  * A Row Condition is similar to a [Row Expression][org.jetbrains.kotlinx.dataframe.documentation.ExpressionsGivenRow] but expects a [Boolean] as result.
- *
  */
 internal interface SelectingRows {
 
diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/ColumnsSelectionDsl.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/ColumnsSelectionDsl.kt
@@ -24,14 +24,14 @@ import kotlin.reflect.typeOf
 /**
  * Referring to a column in the selection DSL can be done in several ways corresponding to all
  * [Access APIs][AccessApi]:
- * TODO
+ * TODO: [Issue #286](https://github.com/Kotlin/dataframe/issues/286)
  */
 private interface CommonColumnSelectionExamples
 
 /** [Column Selection DSL][ColumnSelectionDsl] */
 internal interface ColumnSelectionDslLink
 
-/** TODO: Put examples and explanations here */
+/** TODO: [Issue #286](https://github.com/Kotlin/dataframe/issues/286) */
 public interface ColumnSelectionDsl<out T> : ColumnsContainer<T> {
 
     public operator fun <C> ColumnReference<C>.invoke(): DataColumn<C> = get(this)
@@ -50,7 +50,7 @@ public interface ColumnSelectionDsl<out T> : ColumnsContainer<T> {
 /** [Columns Selection DSL][ColumnsSelectionDsl] */
 internal interface ColumnsSelectionDslLink
 
-/** TODO: Put examples and explanations here */
+/** TODO: [Issue #286](https://github.com/Kotlin/dataframe/issues/286) */
 public interface ColumnsSelectionDsl<out T> : ColumnSelectionDsl<T>, SingleColumn<DataRow<T>> {
 
     public fun <C> ColumnSet<C>.first(condition: ColumnFilter<C>): SingleColumn<C> =
diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/Nulls.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/Nulls.kt
@@ -9,32 +9,6 @@ import org.jetbrains.kotlinx.dataframe.impl.columns.toColumnSet
 import org.jetbrains.kotlinx.dataframe.impl.columns.toColumns
 import kotlin.reflect.KProperty
 
-/**
- * ## `NaN`
- * [Floats][Float] or [Doubles][Double] can be represented as [Float.NaN] or [Double.NaN], respectively,
- * in cases where a mathematical operation is undefined, such as dividing by zero.
- *
- * You can also use [fillNaNs][fillNaNs] to replace `NaNs` in certain columns with a given value or expression
- * or [dropNaNs][dropNaNs] to drop rows with `NaNs` in them.
- *
- * @see NA
- */
-internal interface NaN
-
-/**
- * ## `NA`
- * `NA` in Dataframe can be seen as "[NaN] or `null`".
- *
- * [Floats][Float] or [Doubles][Double] can be represented as [Float.NaN] or [Double.NaN], respectively,
- * in cases where a mathematical operation is undefined, such as dividing by zero.
- *
- * You can also use [fillNA][fillNA] to replace `NAs` in certain columns with a given value or expression
- * or [dropNA][dropNA] to drop rows with `NAs` in them.
- *
- * @see NaN
- */
-internal interface NA
-
 // region fillNulls
 
 /**
@@ -60,7 +34,9 @@ private interface SetFillNullsOperationArg
  * @include [FillNulls] {@comment Description of the fillNulls operation.}
  * @include [LineBreak]
  * @include [Update.Columns] {@comment Description of what this function expects the user to do: select columns}
+ *
  * ## This Fill Nulls Overload
+ *
  */
 private interface CommonFillNullsFunctionDoc
 
@@ -97,7 +73,7 @@ public fun <T, C> DataFrame<T>.fillNulls(vararg columns: ColumnReference<C>): Up
     fillNulls { columns.toColumns() }
 
 /**
- * TODO this will be deprecated
+ * TODO this will be deprecated [PR #286](https://github.com/Kotlin/dataframe/pull/320)
  */
 public fun <T, C> DataFrame<T>.fillNulls(columns: Iterable<ColumnReference<C>>): Update<T, C?> =
     fillNulls { columns.toColumnSet() }
@@ -186,7 +162,7 @@ public fun <T, C> DataFrame<T>.fillNaNs(vararg columns: ColumnReference<C>): Upd
     fillNaNs { columns.toColumns() }
 
 /**
- * TODO this will be deprecated
+ * TODO this will be deprecated [PR #286](https://github.com/Kotlin/dataframe/pull/320)
  */
 public fun <T, C> DataFrame<T>.fillNaNs(columns: Iterable<ColumnReference<C>>): Update<T, C> =
     fillNaNs { columns.toColumnSet() }
@@ -255,7 +231,7 @@ public fun <T, C> DataFrame<T>.fillNA(vararg columns: ColumnReference<C>): Updat
     fillNA { columns.toColumns() }
 
 /**
- * TODO this will be deprecated
+ * TODO this will be deprecated [PR #286](https://github.com/Kotlin/dataframe/pull/320)
  */
 public fun <T, C> DataFrame<T>.fillNA(columns: Iterable<ColumnReference<C>>): Update<T, C?> =
     fillNA { columns.toColumnSet() }
@@ -358,7 +334,7 @@ public fun <T> DataFrame<T>.dropNulls(vararg columns: AnyColumnReference, whereA
     dropNulls(whereAllNull) { columns.toColumns() }
 
 /**
- * TODO will be deprecated
+ * TODO this will be deprecated [PR #286](https://github.com/Kotlin/dataframe/pull/320)
  */
 public fun <T> DataFrame<T>.dropNulls(
     columns: Iterable<AnyColumnReference>,
@@ -452,7 +428,7 @@ public fun <T> DataFrame<T>.dropNA(vararg columns: AnyColumnReference, whereAllN
     dropNA(whereAllNA) { columns.toColumns() }
 
 /**
- * TODO will be deprecated
+ * TODO this will be deprecated [PR #286](https://github.com/Kotlin/dataframe/pull/320)
  */
 public fun <T> DataFrame<T>.dropNA(columns: Iterable<AnyColumnReference>, whereAllNA: Boolean = false): DataFrame<T> =
     dropNA(whereAllNA) { columns.toColumnSet() }
@@ -554,9 +530,12 @@ public fun <T> DataFrame<T>.dropNaNs(vararg columns: AnyColumnReference, whereAl
     dropNaNs(whereAllNaN) { columns.toColumns() }
 
 /**
- * TODO will be deprecated
+ * TODO this will be deprecated [PR #286](https://github.com/Kotlin/dataframe/pull/320)
  */
-public fun <T> DataFrame<T>.dropNaNs(columns: Iterable<AnyColumnReference>, whereAllNaN: Boolean = false): DataFrame<T> =
+public fun <T> DataFrame<T>.dropNaNs(
+    columns: Iterable<AnyColumnReference>,
+    whereAllNaN: Boolean = false,
+): DataFrame<T> =
     dropNaNs(whereAllNaN) { columns.toColumnSet() }
 
 /**
diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/update.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/update.kt
@@ -127,7 +127,7 @@ public fun <T, C> DataFrame<T>.update(vararg columns: ColumnReference<C>): Updat
     update { columns.toColumns() }
 
 /**
- * TODO this will be deprecated
+ * TODO this will be deprecated [PR #286](https://github.com/Kotlin/dataframe/pull/320)
  */
 public fun <T, C> DataFrame<T>.update(columns: Iterable<ColumnReference<C>>): Update<T, C> =
     update { columns.toColumnSet() }
diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/AccessApi.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/AccessApi.kt
@@ -95,4 +95,4 @@ internal interface AccessApi {
 }
 
 /** [Access API][AccessApi] */
-internal interface AccessApiLink
+public const val AccessApiLink: Int = 0
diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/ExpressionsGivenRow.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/ExpressionsGivenRow.kt
@@ -20,11 +20,11 @@ import org.jetbrains.kotlinx.dataframe.RowValueExpression as DfRowValueExpressio
  * for instance in [update.with][Update.with], and [convert.notNull][Convert.notNull]
  * (using [RowValueExpression][DfRowValueExpression]).
  *
- * Note:
+ * NOTE:
  *
  * @include [AddDataRowNote]
  *
- * A Row Expression is similar to a {@include [RowConditionLink]} but that expects a [Boolean] as result.
+ * A {@include [RowExpressionLink]} is similar to a {@include [RowConditionLink]} but that expects a [Boolean] as result.
  */
 internal interface ExpressionsGivenRow {
 
diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/NA.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/NA.kt
@@ -0,0 +1,18 @@
+package org.jetbrains.kotlinx.dataframe.documentation
+
+import org.jetbrains.kotlinx.dataframe.api.dropNA
+import org.jetbrains.kotlinx.dataframe.api.fillNA
+
+/**
+ * ## `NA`
+ * `NA` in Dataframe can be seen as "[NaN] or `null`".
+ *
+ * [Floats][Float] or [Doubles][Double] can be represented as [Float.NaN] or [Double.NaN], respectively,
+ * in cases where a mathematical operation is undefined, such as dividing by zero.
+ *
+ * You can also use [fillNA][fillNA] to replace `NAs` in certain columns with a given value or expression
+ * or [dropNA][dropNA] to drop rows with `NAs` in them.
+ *
+ * @see NaN
+ */
+internal interface NA
diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/NaN.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/NaN.kt
@@ -0,0 +1,16 @@
+package org.jetbrains.kotlinx.dataframe.documentation
+
+import org.jetbrains.kotlinx.dataframe.api.dropNaNs
+import org.jetbrains.kotlinx.dataframe.api.fillNaNs
+
+/**
+ * ## `NaN`
+ * [Floats][Float] or [Doubles][Double] can be represented as [Float.NaN] or [Double.NaN], respectively,
+ * in cases where a mathematical operation is undefined, such as dividing by zero.
+ *
+ * You can also use [fillNaNs][fillNaNs] to replace `NaNs` in certain columns with a given value or expression
+ * or [dropNaNs][dropNaNs] to drop rows with `NaNs` in them.
+ *
+ * @see NA
+ */
+internal interface NaN
diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/SelectingColumns.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/SelectingColumns.kt
@@ -10,12 +10,6 @@ import org.jetbrains.kotlinx.dataframe.columns.SingleColumn
 import org.jetbrains.kotlinx.dataframe.documentation.SelectingColumns.*
 import kotlin.reflect.KProperty
 
-/** {@comment
- * In this file we provide documentation for high-level operations such as
- * the operation of selecting columns.
- * }
- */
-
 /** [Selecting Columns][SelectingColumns] */
 internal interface SelectingColumnsLink
 
diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/SelectingRows.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/SelectingRows.kt
@@ -1,7 +1,11 @@
 package org.jetbrains.kotlinx.dataframe.documentation
 
-import org.jetbrains.kotlinx.dataframe.*
+import org.jetbrains.kotlinx.dataframe.RowFilter
+import org.jetbrains.kotlinx.dataframe.RowValueFilter
 import org.jetbrains.kotlinx.dataframe.api.*
+import org.jetbrains.kotlinx.dataframe.documentation.SelectingRows.RowConditionLink
+import org.jetbrains.kotlinx.dataframe.documentation.SelectingRows.RowValueConditionLink
+import org.jetbrains.kotlinx.dataframe.index
 
 /**
  * ## Selecting Rows
@@ -14,7 +18,6 @@ import org.jetbrains.kotlinx.dataframe.api.*
  * (using [RowValueFilter]).
  *
  * A Row Condition is similar to a {@include [RowExpressionsLink]} but expects a [Boolean] as result.
- * {@comment TODO Is `where` present everywhere it should be?}
  */
 internal interface SelectingRows {
 
diff --git a/examples/idea-examples/movies/build.gradle.kts b/examples/idea-examples/movies/build.gradle.kts
@@ -16,7 +16,6 @@ application.mainClass.set("org.jetbrains.kotlinx.dataframe.examples.movies.Movie
 
 dependencies {
     implementation(project(":core"))
-    implementation(project(":dataframe-openapi"))
 }
 
 tasks.withType<KotlinCompile> {

Original file line number	Diff line number	Diff line change
`@@ -135,4 +135,4 @@ internal interface AccessApi {`
`135`	`135`	`}`
`136`	`136`
`137`	`137`	`/** [Access API][AccessApi] */`
`138`		`-internal interface AccessApiLink`
	`138`	`+public const val AccessApiLink: Int = 0`
Original file line number	Diff line number	Diff line change
`@@ -20,14 +20,14 @@ import org.jetbrains.kotlinx.dataframe.RowValueExpression as DfRowValueExpressio`
`20`	`20`	`* for instance in [update.with][Update.with], and [convert.notNull][Convert.notNull]`
`21`	`21`	`* (using [RowValueExpression][DfRowValueExpression]).`
`22`	`22`	`*`
`23`		`- * Note:`
	`23`	`+ * NOTE:`
`24`	`24`	`*`
`25`	`25`	`* [update with][org.jetbrains.kotlinx.dataframe.api.Update.with]- and [add][org.jetbrains.kotlinx.dataframe.api.add]-like expressions use [AddDataRow][org.jetbrains.kotlinx.dataframe.api.AddDataRow] instead of [DataRow][org.jetbrains.kotlinx.dataframe.DataRow] as the DSL's receiver type.`
`26`	`26`	`* This is an extension to [RowValueExpression][org.jetbrains.kotlinx.dataframe.RowValueExpression] and`
`27`	`27`	`* [RowExpression][org.jetbrains.kotlinx.dataframe.RowExpression] that provides access to`
`28`	`28`	`* the modified/generated value of the preceding row ([AddDataRow.newValue][org.jetbrains.kotlinx.dataframe.api.AddDataRow.newValue]).`
`29`	`29`	`*`
`30`		`- * A Row Expression is similar to a [Row Condition][org.jetbrains.kotlinx.dataframe.documentation.SelectingRows] but that expects a [Boolean][Boolean] as result.`
	`30`	`+ * A [Row Expression][org.jetbrains.kotlinx.dataframe.documentation.ExpressionsGivenRow.RowExpression.WithExample] is similar to a [Row Condition][org.jetbrains.kotlinx.dataframe.documentation.SelectingRows] but that expects a [Boolean][Boolean] as result.`
`31`	`31`	`*/`
`32`	`32`	`internal interface ExpressionsGivenRow {`
`33`	`33`