Merge pull request #214 from Kotlin/jpc-kdoc-reuse

KDocs start using Doc Preprocessor Gradle plugin

Author: Jolanrensen

core/build.gradle.kts

@@ -69,10 +69,12 @@ val addGeneratedSourcesToGit by tasks.creating(GitTask::class) {
 
 // Backup the kotlin source files location
 val kotlinMainSources = kotlin.sourceSets.main.get().kotlin.sourceDirectories
+val kotlinTestSources = kotlin.sourceSets.test.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 + kotlinTestSources) // Include both test and main sources for cross-referencing
+        .filterNot { "build/generated" in it.path }, // Exclude generated sources
 ) {
     target = file(generatedSourcesFolderName)
     processors = listOf(
@@ -107,8 +109,9 @@ tasks.withType<Jar> {
     doFirst {
         kotlin.sourceSets.main {
             kotlin.setSrcDirs(
-                processKDocsMain.targets +
-                    kotlinMainSources.filter { "build/generated" in it.path } // Include generated sources (which were excluded above)
+                processKDocsMain.targets
+                    .filterNot { "src/test/kotlin" in it.path || "src/test/java" in it.path } // filter out test sources again
+                    .plus(kotlinMainSources.filter { "build/generated" in it.path }) // Include generated sources (which were excluded above)
             )
         }
     }

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

@@ -74,6 +74,17 @@ 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

@@ -11,36 +11,27 @@ import org.jetbrains.kotlinx.dataframe.DataColumn
 import org.jetbrains.kotlinx.dataframe.DataFrame
 import org.jetbrains.kotlinx.dataframe.DataRow
 import org.jetbrains.kotlinx.dataframe.Predicate
-import org.jetbrains.kotlinx.dataframe.columns.ColumnAccessor
-import org.jetbrains.kotlinx.dataframe.columns.ColumnGroup
-import org.jetbrains.kotlinx.dataframe.columns.ColumnPath
-import org.jetbrains.kotlinx.dataframe.columns.ColumnReference
-import org.jetbrains.kotlinx.dataframe.columns.ColumnResolutionContext
-import org.jetbrains.kotlinx.dataframe.columns.ColumnSet
-import org.jetbrains.kotlinx.dataframe.columns.ColumnWithPath
-import org.jetbrains.kotlinx.dataframe.columns.FrameColumn
-import org.jetbrains.kotlinx.dataframe.columns.SingleColumn
-import org.jetbrains.kotlinx.dataframe.columns.renamedReference
+import org.jetbrains.kotlinx.dataframe.columns.*
+import org.jetbrains.kotlinx.dataframe.documentation.AccessApi
 import org.jetbrains.kotlinx.dataframe.hasNulls
 import org.jetbrains.kotlinx.dataframe.impl.columnName
-import org.jetbrains.kotlinx.dataframe.impl.columns.ColumnsList
-import org.jetbrains.kotlinx.dataframe.impl.columns.DistinctColumnSet
-import org.jetbrains.kotlinx.dataframe.impl.columns.addPath
-import org.jetbrains.kotlinx.dataframe.impl.columns.allColumnsExcept
-import org.jetbrains.kotlinx.dataframe.impl.columns.changePath
-import org.jetbrains.kotlinx.dataframe.impl.columns.createColumnSet
-import org.jetbrains.kotlinx.dataframe.impl.columns.getAt
-import org.jetbrains.kotlinx.dataframe.impl.columns.getChildrenAt
-import org.jetbrains.kotlinx.dataframe.impl.columns.single
-import org.jetbrains.kotlinx.dataframe.impl.columns.toColumns
-import org.jetbrains.kotlinx.dataframe.impl.columns.top
-import org.jetbrains.kotlinx.dataframe.impl.columns.transform
-import org.jetbrains.kotlinx.dataframe.impl.columns.transformSingle
+import org.jetbrains.kotlinx.dataframe.impl.columns.*
 import org.jetbrains.kotlinx.dataframe.impl.columns.tree.dfs
 import kotlin.reflect.KProperty
 import kotlin.reflect.KType
 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: [Issue #286](https://github.com/Kotlin/dataframe/issues/286)
+ */
+private interface CommonColumnSelectionExamples
+
+/** [Column Selection DSL][ColumnSelectionDsl] */
+internal interface ColumnSelectionDslLink
+
+/** 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)
@@ -56,6 +47,10 @@ 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: [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> =
@@ -70,24 +65,26 @@ public interface ColumnsSelectionDsl<out T> : ColumnSelectionDsl<T>, SingleColum
 
     public fun ColumnsContainer<*>.group(name: String): ColumnGroupReference = name.toColumnOf()
 
-    public operator fun String.rangeTo(endInclusive: String): ColumnSet<*> = toColumnAccessor().rangeTo(endInclusive.toColumnAccessor())
-
-    public operator fun AnyColumnReference.rangeTo(endInclusive: AnyColumnReference): ColumnSet<*> = object : ColumnSet<Any?> {
-        override fun resolve(context: ColumnResolutionContext): List<ColumnWithPath<Any?>> {
-            val startPath = this@rangeTo.resolveSingle(context)!!.path
-            val endPath = endInclusive.resolveSingle(context)!!.path
-            val parentPath = startPath.parent()!!
-            require(parentPath == endPath.parent()) { "Start and end columns have different parent column paths" }
-            val parentCol = context.df.getColumnGroup(parentPath)
-            val startIndex = parentCol.getColumnIndex(startPath.name)
-            val endIndex = parentCol.getColumnIndex(endPath.name)
-            return (startIndex..endIndex).map {
-                parentCol.getColumn(it).let {
-                    it.addPath(parentPath + it.name)
+    public operator fun String.rangeTo(endInclusive: String): ColumnSet<*> =
+        toColumnAccessor().rangeTo(endInclusive.toColumnAccessor())
+
+    public operator fun AnyColumnReference.rangeTo(endInclusive: AnyColumnReference): ColumnSet<*> =
+        object : ColumnSet<Any?> {
+            override fun resolve(context: ColumnResolutionContext): List<ColumnWithPath<Any?>> {
+                val startPath = this@rangeTo.resolveSingle(context)!!.path
+                val endPath = endInclusive.resolveSingle(context)!!.path
+                val parentPath = startPath.parent()!!
+                require(parentPath == endPath.parent()) { "Start and end columns have different parent column paths" }
+                val parentCol = context.df.getColumnGroup(parentPath)
+                val startIndex = parentCol.getColumnIndex(startPath.name)
+                val endIndex = parentCol.getColumnIndex(endPath.name)
+                return (startIndex..endIndex).map {
+                    parentCol.getColumn(it).let {
+                        it.addPath(parentPath + it.name)
+                    }
                 }
             }
         }
-    }
 
     public fun none(): ColumnSet<*> = ColumnsList<Any?>(emptyList())
 
@@ -115,7 +112,8 @@ public interface ColumnsSelectionDsl<out T> : ColumnSelectionDsl<T>, SingleColum
 
     public fun <C> ColumnSet<DataRow<C>>.select(vararg columns: String): ColumnSet<*> = select { columns.toColumns() }
 
-    public fun <C, R> ColumnSet<DataRow<C>>.select(vararg columns: KProperty<R>): ColumnSet<R> = select { columns.toColumns() }
+    public fun <C, R> ColumnSet<DataRow<C>>.select(vararg columns: KProperty<R>): ColumnSet<R> =
+        select { columns.toColumns() }
 
     public fun <C, R> ColumnSet<DataRow<C>>.select(selector: ColumnsSelector<C, R>): ColumnSet<R> = createColumnSet {
         this@select.resolve(it).flatMap { group ->
@@ -145,7 +143,8 @@ public interface ColumnsSelectionDsl<out T> : ColumnSelectionDsl<T>, SingleColum
 
     // region allDfs
 
-    public fun ColumnSet<*>.allDfs(includeGroups: Boolean = false): ColumnSet<Any?> = if (includeGroups) dfs { true } else dfs { !it.isColumnGroup() }
+    public fun ColumnSet<*>.allDfs(includeGroups: Boolean = false): ColumnSet<Any?> =
+        if (includeGroups) dfs { true } else dfs { !it.isColumnGroup() }
 
     public fun String.allDfs(includeGroups: Boolean = false): ColumnSet<Any?> = toColumnAccessor().allDfs(includeGroups)
 
@@ -242,7 +241,9 @@ public interface ColumnsSelectionDsl<out T> : ColumnSelectionDsl<T>, SingleColum
 
     public fun <C> col(property: KProperty<C>): ColumnAccessor<C> = property.toColumnAccessor()
 
-    public operator fun ColumnSet<*>.get(colName: String): ColumnSet<Any?> = transform { it.mapNotNull { it.getChild(colName) } }
+    public operator fun ColumnSet<*>.get(colName: String): ColumnSet<Any?> =
+        transform { it.mapNotNull { it.getChild(colName) } }
+
     public operator fun <C> ColumnSet<*>.get(column: ColumnReference<C>): ColumnSet<C> = cols(column)
 
     public fun SingleColumn<AnyRow>.take(n: Int): ColumnSet<*> = transformSingle { it.children().take(n) }
@@ -288,8 +289,11 @@ public interface ColumnsSelectionDsl<out T> : ColumnSelectionDsl<T>, SingleColum
     public infix fun <C> ColumnReference<C>.into(column: KProperty<*>): ColumnReference<C> = named(column.columnName)
 
     public infix fun String.into(newName: String): ColumnReference<Any?> = toColumnAccessor().into(newName)
-    public infix fun String.into(column: ColumnAccessor<*>): ColumnReference<Any?> = toColumnAccessor().into(column.name())
-    public infix fun String.into(column: KProperty<*>): ColumnReference<Any?> = toColumnAccessor().into(column.columnName)
+    public infix fun String.into(column: ColumnAccessor<*>): ColumnReference<Any?> =
+        toColumnAccessor().into(column.name())
+
+    public infix fun String.into(column: KProperty<*>): ColumnReference<Any?> =
+        toColumnAccessor().into(column.columnName)
 
     public infix fun <C> ColumnReference<C>.named(newName: String): ColumnReference<C> = renamedReference(newName)
     public infix fun <C> ColumnReference<C>.named(name: KProperty<*>): ColumnReference<C> = named(name.columnName)
@@ -311,6 +315,7 @@ public interface ColumnsSelectionDsl<out T> : ColumnSelectionDsl<T>, SingleColum
     public infix fun <C> KProperty<C>.and(other: String): ColumnSet<Any?> = toColumnAccessor() and other
     public infix fun <C> KProperty<C>.and(other: KProperty<C>): ColumnSet<C> =
         toColumnAccessor() and other.toColumnAccessor()
+
     public infix fun <C> KProperty<C>.and(other: ColumnsSelector<T, C>): ColumnSet<C> = toColumnAccessor() and other()
 
     // endregion
@@ -339,7 +344,7 @@ public interface ColumnsSelectionDsl<out T> : ColumnSelectionDsl<T>, SingleColum
 public inline fun <T, reified R> ColumnsSelectionDsl<T>.expr(
     name: String = "",
     infer: Infer = Infer.Nulls,
-    noinline expression: AddExpression<T, R>
+    noinline expression: AddExpression<T, R>,
 ): DataColumn<R> = mapToColumn(name, infer, expression)
 
 internal fun <T, C> ColumnsSelector<T, C>.filter(predicate: (ColumnWithPath<C>) -> Boolean): ColumnsSelector<T, C> =