Merge branch 'master' into explode_kdocs

Author: AndreiKingsley

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

@@ -137,14 +137,16 @@ public typealias ColumnsSelector<T, C> = Selector<ColumnsSelectionDsl<T>, Column
 // region filters
 
 /**
- * ## Row Filter
+ * A lambda expression that evaluates a row of the [DataFrame]
+ * and returns a [Boolean] indicating whether the row should be included in the result.
  *
- * [RowFilter] is a lambda function expecting a [Boolean] result given an instance of [DataRow]`<T>` as context
- * (`this` and `it`).
+ * The lambda has access to the [`DataRow<T>`][DataRow] both as `this` and as `it`,
+ * enabling concise and readable conditions.
  *
- * Return `true` if the row should be included in the result.
+ * Commonly used in operations such as [filter][org.jetbrains.kotlinx.dataframe.api.filter],
+ * [drop][org.jetbrains.kotlinx.dataframe.api.drop], and others.
  *
- * Shorthand for:
+ * Equivalent to:
  * ```kotlin
  * DataRow<T>.(it: DataRow<T>) -> Boolean
  * ```

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

@@ -18,10 +18,18 @@ import org.jetbrains.kotlinx.dataframe.impl.columns.TransformableColumnSet
 import org.jetbrains.kotlinx.dataframe.impl.getTrueIndices
 import org.jetbrains.kotlinx.dataframe.indices
 import org.jetbrains.kotlinx.dataframe.util.DEPRECATED_ACCESS_API
+import org.jetbrains.kotlinx.dataframe.util.FILTER_BY
+import org.jetbrains.kotlinx.dataframe.util.FILTER_BY_REPLACE
 import kotlin.reflect.KProperty
 
 // region DataColumn
 
+/**
+ * Returns a new [DataColumn] containing only the elements that match the given [predicate].
+ *
+ * @param predicate the condition used to filter the elements in the DataColumn.
+ * @return a new DataColumn containing elements that satisfy the predicate.
+ */
 public inline fun <T> DataColumn<T>.filter(predicate: Predicate<T>): DataColumn<T> =
     indices
         .filter { predicate(get(it)) }
@@ -31,21 +39,52 @@ public inline fun <T> DataColumn<T>.filter(predicate: Predicate<T>): DataColumn<
 
 // region DataFrame
 
+/**
+ * Filters the rows of this [DataFrame] based on the provided [RowFilter].
+ * Returns a new [DataFrame] containing only the rows that satisfy the given [predicate].
+ *
+ * A [RowFilter] provides each row as a lambda argument, allowing you to define filtering logic
+ * using a [Boolean] condition.
+ *
+ * This can include [column groups][org.jetbrains.kotlinx.dataframe.columns.ColumnGroup] and nested columns.
+ *
+ * For more information, see: [See `filter` on the documentation website.](https://kotlin.github.io/dataframe/filter.html)
+ *
+ * See also:
+ *  - [drop][DataFrame.drop], which drops rows based on values within the row.
+ *  - [distinct][DataFrame.distinct], which filters out rows with duplicated values.
+ *
+ * ### Example
+ * ```kotlin
+ * // Select rows where the value in the "age" column is greater than 18
+ * // and the "name/firstName" column starts with 'A'
+ * df.filter { age > 18 && name.firstName.startsWith("A") }
+ * ```
+ *
+ * @param predicate A lambda that takes a row (twice for compatibility) and returns `true`
+ * if the row should be included in the result.
+ * @return A new [DataFrame] containing only the rows that satisfy the predicate.
+ */
 public inline fun <T> DataFrame<T>.filter(predicate: RowFilter<T>): DataFrame<T> =
     indices().filter {
         val row = get(it)
         predicate(row, row)
     }.let { get(it) }
 
+@Deprecated(message = FILTER_BY, replaceWith = ReplaceWith(FILTER_BY_REPLACE), level = DeprecationLevel.ERROR)
 public fun <T> DataFrame<T>.filterBy(column: ColumnSelector<T, Boolean>): DataFrame<T> =
     getRows(getColumn(column).toList().getTrueIndices())
 
+@Suppress("DEPRECATION_ERROR")
+@Deprecated(message = FILTER_BY, replaceWith = ReplaceWith(FILTER_BY_REPLACE), level = DeprecationLevel.ERROR)
 public fun <T> DataFrame<T>.filterBy(column: String): DataFrame<T> = filterBy { column.toColumnOf() }
 
+@Suppress("DEPRECATION_ERROR")
 @Deprecated(DEPRECATED_ACCESS_API)
 @AccessApiOverload
 public fun <T> DataFrame<T>.filterBy(column: ColumnReference<Boolean>): DataFrame<T> = filterBy { column }
 
+@Suppress("DEPRECATION_ERROR")
 @Deprecated(DEPRECATED_ACCESS_API)
 @AccessApiOverload
 public fun <T> DataFrame<T>.filterBy(column: KProperty<Boolean>): DataFrame<T> = filterBy { column.toColumnAccessor() }

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

@@ -273,7 +273,7 @@ public fun <T, C, K, R> Gather<T, C, K, R>.where(filter: RowValueFilter<T, C>):
  * Filters out `null` values from the columns previously selected by [gather],
  * keeping only non-null entries.
  *
- * A special case of [where].
+ * A special case of [Gather.where].
  *
  * It's an intermediate step; returns a new [Gather] with filtered value columns.
  *

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

@@ -110,6 +110,9 @@ internal const val CONVERT_TO_URL_REPLACE = "convertToUrl()"
 internal const val TO_URL = "This function is replaced by `toUrl()`. $MESSAGE_1_0"
 internal const val TO_URL_REPLACE = "toUrl()"
 
+internal const val FILTER_BY = "This function is deprecated in favor of `filter { }`. $MESSAGE_1_0"
+internal const val FILTER_BY_REPLACE = "filter { column }"
+
 // endregion
 
 // region WARNING in 1.0, ERROR in 1.1

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

@@ -20,7 +20,6 @@ import org.jetbrains.kotlinx.dataframe.api.dropNulls
 import org.jetbrains.kotlinx.dataframe.api.dropWhile
 import org.jetbrains.kotlinx.dataframe.api.fillNaNs
 import org.jetbrains.kotlinx.dataframe.api.filter
-import org.jetbrains.kotlinx.dataframe.api.filterBy
 import org.jetbrains.kotlinx.dataframe.api.first
 import org.jetbrains.kotlinx.dataframe.api.forEach
 import org.jetbrains.kotlinx.dataframe.api.gather
@@ -324,22 +323,6 @@ class Access : TestBase() {
         // SampleEnd
     }
 
-    @Test
-    @TransformDataFrameExpressions
-    fun filterBy_properties() {
-        // SampleStart
-        df.filterBy { isHappy }
-        // SampleEnd
-    }
-
-    @Test
-    @TransformDataFrameExpressions
-    fun filterBy_strings() {
-        // SampleStart
-        df.filterBy("isHappy")
-        // SampleEnd
-    }
-
     @Test
     @TransformDataFrameExpressions
     fun dropWhere_properties() {

core/generated-sources/src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/api/Access.kt

@@ -1,8 +1,9 @@
+@file:ExcludeFromSources
+
 package org.jetbrains.kotlinx.dataframe.documentation
 
 /**
  * If the specified path is partially or fully missing — that is, if any segment of the path
  * does not correspond to an existing column or column group — all missing parts will be created automatically.
  */
-@ExcludeFromSources
 internal interface ColumnPathCreation