Merge branch 'master' into jpc-kdoc-reuse

# Conflicts:
#	core/build.gradle.kts
#	core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/aliases.kt
#	core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/ColumnsSelectionDsl.kt
#	core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/Nulls.kt
#	core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/add.kt
#	core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/gather.kt
#	core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/reorder.kt
#	core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/select.kt
#	core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/toDataFrame.kt
#	core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/update.kt
#	core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/impl/api/convertTo.kt
#	core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/impl/api/gather.kt
#	core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/impl/api/reorder.kt
#	core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/impl/api/update.kt
#	core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/impl/columns/constructors.kt

Author: Jolanrensen

build.gradle.kts

@@ -14,6 +14,8 @@ plugins {
     id("org.jetbrains.dokka") version libs.versions.dokka
     id("org.jetbrains.kotlinx.kover") version libs.versions.kover
     id("org.jmailen.kotlinter") version libs.versions.ktlint
+    id("nl.jolanrensen.docProcessor") version libs.versions.docProcessor apply false
+    id("xyz.ronella.simple-git") version libs.versions.simpleGit apply false
 }
 
 val jupyterApiTCRepo: String by project

core/build.gradle.kts

@@ -1,6 +1,7 @@
 import nl.jolanrensen.docProcessor.defaultProcessors.*
 import nl.jolanrensen.docProcessor.gradle.creatingProcessDocTask
 import org.gradle.jvm.tasks.Jar
+import xyz.ronella.gradle.plugin.simple.git.task.GitTask
 
 @Suppress("DSL_SCOPE_VIOLATION", "UnstableApiUsage")
 plugins {
@@ -14,8 +15,9 @@ plugins {
     id("org.jetbrains.kotlinx.kover")
     id("org.jmailen.kotlinter")
     id("org.jetbrains.kotlinx.dataframe")
-//    id("com.github.jolanrensen.docProcessorGradlePlugin") version "v0.1.0"
-    id("nl.jolanrensen.docProcessor") version "0.1.1"
+    id("nl.jolanrensen.docProcessor")
+    id("xyz.ronella.simple-git")
+    idea
 }
 
 group = "org.jetbrains.kotlinx"
@@ -58,58 +60,62 @@ kotlin.sourceSets {
     }
 }
 
+val generatedSourcesFolderName = "generated-sources"
+val addGeneratedSourcesToGit by tasks.creating(GitTask::class) {
+    directory.set(file("."))
+    command.set("add")
+    args.set(listOf("-A", generatedSourcesFolderName))
+}
+
 // Backup the kotlin source files location
 val kotlinMainSources = kotlin.sourceSets.main.get().kotlin.sourceDirectories
 
+// Task to generate the processed documentation
 val processKDocsMain by creatingProcessDocTask(
-    sources = kotlinMainSources.filterNot { "build/generated" in it.path } // Exclude generated sources
+    sources = kotlinMainSources.filterNot { "build/generated" in it.path }, // Exclude generated sources
 ) {
-    target = file("generated-sources")
+    target = file(generatedSourcesFolderName)
     processors = listOf(
         INCLUDE_DOC_PROCESSOR,
         INCLUDE_FILE_DOC_PROCESSOR,
         INCLUDE_ARG_DOC_PROCESSOR,
         COMMENT_DOC_PROCESSOR,
         SAMPLE_DOC_PROCESSOR,
     )
-}
 
-// As a bonus, this will update dokka if you use that
-tasks.withType<org.jetbrains.dokka.gradle.AbstractDokkaLeafTask> {
-    dependsOn(processKDocsMain)
-    dokkaSourceSets {
-        all {
-            sourceRoot(processKDocsMain.target.get())
+    task {
+        doLast {
+            // ensure generated sources are added to git
+            addGeneratedSourcesToGit.executeCommand()
         }
     }
 }
 
+// Exclude the generated/processed sources from the IDE
+idea {
+    module {
+        excludeDirs.add(file(generatedSourcesFolderName))
+    }
+}
+
 // Modify all Jar tasks such that before running the Kotlin sources are set to
-// the target of processKdocIncludeMain and they are returned back to normal afterwards.
+// the target of processKdocMain and they are returned back to normal afterwards.
 tasks.withType<Jar> {
     dependsOn(processKDocsMain)
     outputs.upToDateWhen { false }
 
     doFirst {
-        kotlin {
-            sourceSets {
-                main {
-                    kotlin.setSrcDirs(
-                        processKDocsMain.targets +
-                            kotlinMainSources.filter { "build/generated" in it.path } // Include generated sources (which were excluded above)
-                    )
-                }
-            }
+        kotlin.sourceSets.main {
+            kotlin.setSrcDirs(
+                processKDocsMain.targets +
+                    kotlinMainSources.filter { "build/generated" in it.path } // Include generated sources (which were excluded above)
+            )
         }
     }
 
     doLast {
-        kotlin {
-            sourceSets {
-                main {
-                    kotlin.setSrcDirs(kotlinMainSources)
-                }
-            }
+        kotlin.sourceSets.main {
+            kotlin.setSrcDirs(kotlinMainSources)
         }
     }
 }
@@ -231,3 +237,13 @@ dataframes {
         name = "org.jetbrains.kotlinx.dataframe.samples.api.Repository"
     }
 }
+
+// If we want to use Dokka, make sure to use the preprocessed sources
+tasks.withType<org.jetbrains.dokka.gradle.AbstractDokkaLeafTask> {
+    dependsOn(processKDocsMain)
+    dokkaSourceSets {
+        all {
+            sourceRoot(processKDocsMain.target.get())
+        }
+    }
+}

core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/aliases.kt

@@ -74,17 +74,6 @@ public typealias RowValueExpression<T, C, R> = DataRow<T>.(it: C) -> R
  */
 public typealias RowColumnExpression<T, C, R> = (row: DataRow<T>, col: DataColumn<C>) -> R
 
-/**
- * [ColumnExpression] is used to express or select any instance of `R` using the given instance of [DataColumn]`<C>` as
- * `this` and `it`.
- *
- * Shorthand for:
- * ```kotlin
- * DataColumn<C>.(it: DataColumn<C>) -> R
- * ```
- */
-public typealias ColumnExpression<C, R> = Selector<DataColumn<C>, R>
-
 /**
  * [ColumnSelector] is used to express or select a single column, represented by [SingleColumn]`<C>`, using the
  * context of [ColumnsSelectionDsl]`<T>` as `this` and `it`.

core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/ColumnsSelectionDsl.kt

@@ -41,10 +41,6 @@ import kotlin.reflect.KProperty
 import kotlin.reflect.KType
 import kotlin.reflect.typeOf
 
-/** [Column Selection DSL][ColumnSelectionDsl] */
-internal interface ColumnSelectionDslLink
-
-/** TODO: Put examples and explanations here */
 public interface ColumnSelectionDsl<out T> : ColumnsContainer<T> {
 
     public operator fun <C> ColumnReference<C>.invoke(): DataColumn<C> = get(this)
@@ -60,10 +56,6 @@ public interface ColumnSelectionDsl<out T> : ColumnsContainer<T> {
     public operator fun String.get(column: String): ColumnPath = pathOf(this, column)
 }
 
-/** [Columns Selection DSL][ColumnsSelectionDsl] */
-internal interface ColumnsSelectionDslLink
-
-/** TODO: Put examples and explanations here */
 public interface ColumnsSelectionDsl<out T> : ColumnSelectionDsl<T>, SingleColumn<DataRow<T>> {
 
     public fun <C> ColumnSet<C>.first(condition: ColumnFilter<C>): SingleColumn<C> =