Merge pull request #1134 from Kotlin/convert_kdocs

Convert KDocs

Author: AndrewKis

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

@@ -222,7 +222,7 @@ public fun <T : Number?> DataColumn<T>.cumSum(skipNA: Boolean = defaultCumSumSki
 public fun <T, C : Number?> DataFrame<T>.cumSum(
     skipNA: Boolean = defaultCumSumSkipNA,
     columns: ColumnsSelector<T, C>,
-): DataFrame<T> = convert(columns).to { it.cumSum(skipNA) }
+): DataFrame<T> = convert(columns).asColumn { it.cumSum(skipNA) }
 
 /**
  * ## The CumSum Operation

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

@@ -305,8 +305,26 @@ public fun <T, C> GroupClause<T, C>.into(column: ColumnsSelectionDsl<T>.(ColumnW
  *
  * For more information: [See `group` on the documentation website.](https://kotlin.github.io/dataframe/group.html)
  *
- * Select columns using their [column names][String]
- * ([String API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.StringApi]).
+ * Select or express columns using the [Columns Selection DSL][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl].
+ * (Any (combination of) [Access API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi]).
+ *
+ * This DSL is initiated by a [Columns Selector][org.jetbrains.kotlinx.dataframe.ColumnsSelector] lambda,
+ * which operates in the context of the [Columns Selection DSL][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl] and
+ * expects you to return a [SingleColumn][org.jetbrains.kotlinx.dataframe.columns.SingleColumn] or [ColumnSet][org.jetbrains.kotlinx.dataframe.columns.ColumnSet] (so, a [ColumnsResolver][org.jetbrains.kotlinx.dataframe.columns.ColumnsResolver]).
+ * This is an entity formed by calling any (combination) of the functions
+ * in the DSL that is or can be resolved into one or more columns.
+ *
+ * #### NOTE:
+ * While you can use the [String API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.StringApi] and [KProperties API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.KPropertiesApi]
+ * in this DSL directly with any function, they are NOT valid return types for the
+ * [Columns Selector][org.jetbrains.kotlinx.dataframe.ColumnsSelector] lambda. You'd need to turn them into a [ColumnReference][org.jetbrains.kotlinx.dataframe.columns.ColumnReference] first, for instance
+ * with a function like [`col("name")`][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.col].
+ *
+ * ### Check out: [Columns Selection DSL Grammar][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.DslGrammar]
+ *
+ * &nbsp;&nbsp;&nbsp;&nbsp;
+ *
+ * [See Column Selectors on the documentation website.](https://kotlin.github.io/dataframe/columnselectors.html)
  *
  * ### Examples:
  * ```kotlin

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

@@ -432,7 +432,8 @@ public fun <T, C> Update<T, C>.at(rowRange: IntRange): Update<T, C> = where { in
  *
  *
  * ## See Also
- *  - [Update with][org.jetbrains.kotlinx.dataframe.api.Update.with] to provide a new value for every selected cell giving its row.
+ *  - [Update with][org.jetbrains.kotlinx.dataframe.api.Update.with] to provide a new value for every selected cell giving its row
+ * and its previous value.
  *  - [Update per col][org.jetbrains.kotlinx.dataframe.api.Update.perCol] to provide a new value for every selected cell giving its column.
  * @param [expression] The [Row Column Expression][org.jetbrains.kotlinx.dataframe.documentation.ExpressionsGivenRowAndColumn.RowColumnExpression] to provide a new value for every selected cell giving its row and column.
  */
@@ -459,7 +460,9 @@ public typealias UpdateExpression<T, C, R> = AddDataRow<T>.(C) -> R
  *
  *
  * ## 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.
+ * [update with][org.jetbrains.kotlinx.dataframe.api.Update.with]-,
+ * [convert with][org.jetbrains.kotlinx.dataframe.api.Convert.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]).
@@ -499,7 +502,8 @@ public fun <T, C, R> Update<T, DataRow<C>>.asFrame(expression: DataFrameExpressi
  *  or [DataRow][org.jetbrains.kotlinx.dataframe.DataRow] as Map.
  *
  * ### See Also
- *  - [Update with][org.jetbrains.kotlinx.dataframe.api.Update.with] to provide a new value for every selected cell giving its row.
+ *  - [Update with][org.jetbrains.kotlinx.dataframe.api.Update.with] to provide a new value for every selected cell giving its row
+ * and its previous value.
  *  - [Update per row col][org.jetbrains.kotlinx.dataframe.api.Update.perRowCol] to provide a new value for every selected cell giving its row and column.
  * ### This Per Col Overload
  * Provide a new value for every selected cell per column using a [Map][Map]`<`[colName: String][String]`, value: C>`
@@ -531,7 +535,8 @@ public fun <T, C> Update<T, C>.perCol(values: Map<String, C>): DataFrame<T> =
  *  or [DataRow][org.jetbrains.kotlinx.dataframe.DataRow] as Map.
  *
  * ### See Also
- *  - [Update with][org.jetbrains.kotlinx.dataframe.api.Update.with] to provide a new value for every selected cell giving its row.
+ *  - [Update with][org.jetbrains.kotlinx.dataframe.api.Update.with] to provide a new value for every selected cell giving its row
+ * and its previous value.
  *  - [Update per row col][org.jetbrains.kotlinx.dataframe.api.Update.perRowCol] to provide a new value for every selected cell giving its row and column.
  * ### This Per Col Overload
  * Provide a new value for every selected cell per column using a [Map][Map]`<`[colName: String][String]`, value: C>`
@@ -565,7 +570,8 @@ public fun <T, C> Update<T, C>.perCol(values: AnyRow): DataFrame<T> = perCol(val
  *  or [DataRow][org.jetbrains.kotlinx.dataframe.DataRow] as Map.
  *
  * ### See Also
- *  - [Update with][org.jetbrains.kotlinx.dataframe.api.Update.with] to provide a new value for every selected cell giving its row.
+ *  - [Update with][org.jetbrains.kotlinx.dataframe.api.Update.with] to provide a new value for every selected cell giving its row
+ * and its previous value.
  *  - [Update per row col][org.jetbrains.kotlinx.dataframe.api.Update.perRowCol] to provide a new value for every selected cell giving its row and column.
  * ### This Per Col Overload
  * Provide a new value for every selected cell given its column using a [column expression][org.jetbrains.kotlinx.dataframe.ColumnExpression].

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

@@ -28,7 +28,9 @@ import org.jetbrains.kotlinx.dataframe.RowValueExpression as DfRowValueExpressio
  *
  * 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.
+ * [update with][org.jetbrains.kotlinx.dataframe.api.Update.with]-,
+ * [convert with][org.jetbrains.kotlinx.dataframe.api.Convert.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]).
@@ -48,7 +50,9 @@ internal interface ExpressionsGivenRow {
     interface SetDefaultOperationArg
 
     /**
-     * [update with][org.jetbrains.kotlinx.dataframe.api.Update.with]- and [add][org.jetbrains.kotlinx.dataframe.api.add]-like expressions use [AddDataRow] instead of [DataRow] as the DSL's receiver type.
+     * [update with][org.jetbrains.kotlinx.dataframe.api.Update.with]-,
+     * [convert with][org.jetbrains.kotlinx.dataframe.api.Convert.with]-
+     * and [add][org.jetbrains.kotlinx.dataframe.api.add]-like expressions use [AddDataRow] instead of [DataRow] as the DSL's receiver type.
      * This is an extension to [RowValueExpression][DfRowValueExpression] and
      * [RowExpression][DfRowExpression] that provides access to
      * the modified/generated value of the preceding row ([AddDataRow.newValue]).

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

@@ -26,6 +26,7 @@ import org.jetbrains.kotlinx.dataframe.api.Convert
 import org.jetbrains.kotlinx.dataframe.api.DataSchemaEnum
 import org.jetbrains.kotlinx.dataframe.api.Infer
 import org.jetbrains.kotlinx.dataframe.api.ParserOptions
+import org.jetbrains.kotlinx.dataframe.api.asColumn
 import org.jetbrains.kotlinx.dataframe.api.mapIndexed
 import org.jetbrains.kotlinx.dataframe.api.name
 import org.jetbrains.kotlinx.dataframe.api.to
@@ -70,7 +71,7 @@ internal fun <T, C, R> Convert<T, C>.withRowCellImpl(
     infer: Infer,
     rowConverter: RowValueExpression<T, C, R>,
 ): DataFrame<T> =
-    to { col ->
+    asColumn { col ->
         try {
             df.newColumn(type, col.name, infer) { rowConverter(it, it[col]) }
         } catch (e: ClassCastException) {
@@ -85,7 +86,7 @@ internal fun <T, C, R> Convert<T, C>.convertRowColumnImpl(
     type: KType,
     infer: Infer,
     rowConverter: RowColumnExpression<T, C, R>,
-): DataFrame<T> = to { col -> df.newColumn(type, col.name, infer) { rowConverter(it, col) } }
+): DataFrame<T> = asColumn { col -> df.newColumn(type, col.name, infer) { rowConverter(it, col) } }
 
 /**
  * Specific implementation for [convertToTypeImpl] for [String] -> [Double] conversion

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

@@ -18,6 +18,7 @@ import org.jetbrains.kotlinx.dataframe.DataFrame
 import org.jetbrains.kotlinx.dataframe.DataRow
 import org.jetbrains.kotlinx.dataframe.api.GlobalParserOptions
 import org.jetbrains.kotlinx.dataframe.api.ParserOptions
+import org.jetbrains.kotlinx.dataframe.api.asColumn
 import org.jetbrains.kotlinx.dataframe.api.asColumnGroup
 import org.jetbrains.kotlinx.dataframe.api.asDataColumn
 import org.jetbrains.kotlinx.dataframe.api.cast
@@ -26,7 +27,6 @@ import org.jetbrains.kotlinx.dataframe.api.isColumnGroup
 import org.jetbrains.kotlinx.dataframe.api.isFrameColumn
 import org.jetbrains.kotlinx.dataframe.api.isSubtypeOf
 import org.jetbrains.kotlinx.dataframe.api.map
-import org.jetbrains.kotlinx.dataframe.api.to
 import org.jetbrains.kotlinx.dataframe.columns.TypeSuggestion
 import org.jetbrains.kotlinx.dataframe.columns.size
 import org.jetbrains.kotlinx.dataframe.exceptions.TypeConversionException
@@ -673,7 +673,7 @@ internal fun <T> DataColumn<String?>.parse(parser: StringParser<T>, options: Par
 }
 
 internal fun <T> DataFrame<T>.parseImpl(options: ParserOptions?, columns: ColumnsSelector<T, Any?>): DataFrame<T> =
-    convert(columns).to { col ->
+    convert(columns).asColumn { col ->
         when {
             // when a frame column is requested to be parsed,
             // parse each value/frame column at any depth inside each DataFrame in the frame column

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

@@ -44,6 +44,20 @@ public fun catchHttpResponse(url: URL, body: (InputStream) -> AnyFrame): AnyFram
     }
 }
 
+/**
+ * Converts a list of lists into a [DataFrame].
+ *
+ * By default, treats the first inner list as a header (column names), and the remaining lists as rows.
+ * If [containsColumns] is `true`, interprets each inner list as a column,
+ * where the first element is used as the column name, and the remaining elements as values.
+ *
+ * @param T The type of elements contained in the nested lists.
+ * @param containsColumns If `true`, treats each nested list as a column with its first element as the column name.
+ *                        Otherwise, the first list is treated as the header.
+ *                        Defaults to `false`.
+ * @return A [DataFrame] containing the data from the nested list structure.
+ *         Returns an empty [DataFrame] if the input is empty or invalid.
+ */
 public fun <T> List<List<T>>.toDataFrame(containsColumns: Boolean = false): AnyFrame =
     when {
         containsColumns -> {

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

@@ -92,6 +92,9 @@ internal const val MAX_NO_SKIPNAN = "This function is just here for binary compa
 internal const val MIN_NO_SKIPNAN = "This function is just here for binary compatibility. $MESSAGE_0_16"
 internal const val MEAN_NO_SKIPNAN = "This function is just here for binary compatibility. $MESSAGE_0_16"
 
+internal const val CONVERT_TO = "This to overload will be removed in favor of `asColumn`. $MESSAGE_0_16"
+internal const val CONVERT_TO_REPLACE = "this.asColumn(columnConverter)"
+
 // endregion
 
 // region WARNING in 0.16, ERROR in 0.17

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

@@ -18,7 +18,7 @@ open class ColumnsSelectionDslTests : TestBase() {
 
     protected val dfWithFrames = df
         .add { expr { df } into frameCol }
-        .convert { name }.to {
+        .convert { name }.asColumn {
             val firstName by it.asColumnGroup().firstName
             val lastName by it.asColumnGroup().lastName