rename_kdocs

Author: AndreiKingsley

core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/rename.kt

@@ -3,8 +3,6 @@ package org.jetbrains.kotlinx.dataframe.api
 import org.jetbrains.kotlinx.dataframe.AnyFrame
 import org.jetbrains.kotlinx.dataframe.ColumnsSelector
 import org.jetbrains.kotlinx.dataframe.DataFrame
-import org.jetbrains.kotlinx.dataframe.RowColumnExpression
-import org.jetbrains.kotlinx.dataframe.RowValueExpression
 import org.jetbrains.kotlinx.dataframe.annotations.AccessApiOverload
 import org.jetbrains.kotlinx.dataframe.annotations.HasSchema
 import org.jetbrains.kotlinx.dataframe.annotations.Interpretable
@@ -28,20 +26,20 @@ import org.jetbrains.kotlinx.dataframe.impl.columnName
 import org.jetbrains.kotlinx.dataframe.impl.toCamelCaseByDelimiters
 import org.jetbrains.kotlinx.dataframe.util.DEPRECATED_ACCESS_API
 import kotlin.reflect.KProperty
-import kotlin.reflect.KType
 
 // region DataFrame
 
 /**
- * Renames the specified [columns\] their original values and location within the [DataFrame].
+ * Renames the specified [columns\] keeping their original values and location within the [DataFrame].
  *
- * This function does not immediately convert the columns but instead selects columns to convert and
+ * This function does not immediately rename the columns but instead selects columns to rename and
  * returns a [RenameClause],
  * which serves as an intermediate step.
- * The [RenameClause] object provides methods to transform selected columns using:
- * - [into(name)][RenameClause.into]
- * - [into { nameExpression }][RenameClause.into]
- * - [toCamelCase()][RenameClause.toCamelCase]
+ * The [RenameClause] object provides methods to rename selected columns using:
+ * - [into(name)][RenameClause.into] - renames selected columns to the specified names.
+ * - [into { nameExpression }][RenameClause.into] - renames selected columns using a provided
+ * expression assuming column with its path and returning a new name.
+ * - [toCamelCase()][RenameClause.toCamelCase] - renames all selected columns to "camelCase".
  *
  * Each method returns a new [DataFrame] with the renamed columns.
  *
@@ -61,7 +59,6 @@ internal interface RenameDocs {
      */
     interface RenameSelectingOptions
 
-
     /**
      * ## Rename Operation Grammar
      * {@include [LineBreak]}
@@ -119,9 +116,14 @@ public fun <T> DataFrame<T>.rename(vararg mappings: Pair<String, String>): DataF
  * @include [SelectingColumns.Dsl] {@include [SetRenameOperationArg]}
  * ### Examples:
  * ```kotlin
- * df.rename { oldName }.into("newName")
- * df.convert { colsAtAnyDepth() }.into { it.path.joinToString("->") }
- * df.rename { cols { it.name.contains(".") } }.into { it.path.joinToString("->") }
+ * // Rename "col1" to "width" and "col2" to "length"
+ * df.rename { col1 and col2 }.into("width", "length")
+ *
+ * // Rename all columns using their full path, delimited by "->"
+ * df.rename { colsAtAnyDepth() }.into { it.path.joinToString("->") }
+ *
+ * // Renames all numeric columns to "camelCase"
+ * df.rename { colsOf<Number>() }.toCamelCase()
  * ```
  * @param [columns\] The [Columns Selector][ColumnsSelector] used to select the columns of this [DataFrame] to group.
  */
@@ -137,17 +139,47 @@ public fun <T, C> DataFrame<T>.rename(vararg cols: ColumnReference<C>): RenameCl
 @AccessApiOverload
 public fun <T, C> DataFrame<T>.rename(vararg cols: KProperty<C>): RenameClause<T, C> = rename { cols.toColumnSet() }
 
+/**
+ * @include [CommonRenameDocs]
+ * @include [SelectingColumns.ColumnNames] {@include [SetRenameOperationArg]}
+ * ### Examples:
+ * ```kotlin
+ * // Rename "col1" to "width" and "col2" to "length"
+ * df.rename("col1", "col2").into("width", "length")
+ *
+ * // Renames "arrival_date" and "passport-ID" columns to "camelCase"
+ * df.rename("arrival_date", "passport-ID").toCamelCase()
+ * ```
+ * @param [columns\] The [Columns Names][String] used to select the columns of this [DataFrame] to group.
+ */
 public fun <T> DataFrame<T>.rename(vararg cols: String): RenameClause<T, Any?> = rename { cols.toColumnSet() }
 
+/**
+ * An intermediate class used in the [rename] operation.
+ *
+ * This class itself does not perform any renaming — it is a transitional step
+ * before specifying how to rename the selected columns.
+ * It must be followed by one of the renaming methods
+ * to produce a new [DataFrame] with renamed columns.
+ *
+ * The resulting columns will keep their original values and positions
+ * in the [DataFrame], but their names will be changed.
+ *
+ * Use the following methods to perform the conversion:
+ * - [into(name)][RenameClause.into] — renames selected columns to the specified names.
+ * - [into { nameExpression }][RenameClause.into] — renames selected columns using a custom expression,
+ *   which takes the column and its path and returns a new name.
+ * - [toCamelCase()][RenameClause.toCamelCase] — renames all selected columns to `camelCase`.
+ *
+ * See [Grammar][RenameDocs.Grammar] for more details.
+ */
 @HasSchema(schemaArg = 0)
 public class RenameClause<T, C>(internal val df: DataFrame<T>, internal val columns: ColumnsSelector<T, C>) {
     override fun toString(): String = "RenameClause(df=$df, columns=$columns)"
 }
 
 /**
- * ## Rename to "camelCase"
- *
- * This function renames all columns in this [DataFrame] to the "camelCase" format.
+ * Renames all columns in this [DataFrame] to the "camelCase" format.
  *
  * Removes all delimiters between words and capitalizes each word except the first one.
  * Adds an underscore between consecutive numbers.
@@ -160,7 +192,7 @@ public class RenameClause<T, C>(internal val df: DataFrame<T>, internal val colu
  *
  * Returns a [DataFrame] with updated column names.
  *
- * ### Examples:
+ * ### Renaming Examples
  * ```
  * "snake_case_name" -> "snakeCaseName"
  * "PascalCaseName" -> "pascalCaseName"
@@ -189,6 +221,30 @@ public fun <T> DataFrame<T>.renameToCamelCase(): DataFrame<T> =
 public fun <T, C> RenameClause<T, C>.into(vararg newColumns: ColumnReference<*>): DataFrame<T> =
     into(*newColumns.map { it.name() }.toTypedArray())
 
+/**
+ * Renames the columns selected with [rename] to the specified [newNames],
+ * preserving their values and positions within the [DataFrame].
+ *
+ * The mapping is positional: [newNames] are applied in the order
+ * the columns were selected — the first selected column is renamed to the first name,
+ * the second to the second, and so on.
+ *
+ * For more information: {@include [DocumentationUrls.Rename]}
+ *
+ * Check out [Grammar][RenameDocs.Grammar].
+ *
+ * ### Examples:
+ * ```kotlin
+ * // Rename "col1" to "width" and "col2" to "length"
+ * df.rename("col1", "col2").into("width", "length")
+ *
+ * // Rename "col1" to "width" and "col2" to "length"
+ * df.rename { col1 and col2 }.into("width", "length")
+ * ```
+ *
+ * @param newNames The new names for the selected columns, applied in order of selecting.
+ * @return A new [DataFrame] with the columns renamed.
+ */
 @Refine
 @Interpretable("RenameInto")
 public fun <T, C> RenameClause<T, C>.into(vararg newNames: String): DataFrame<T> = renameImpl(newNames)
@@ -198,13 +254,35 @@ public fun <T, C> RenameClause<T, C>.into(vararg newNames: String): DataFrame<T>
 public fun <T, C> RenameClause<T, C>.into(vararg newNames: KProperty<*>): DataFrame<T> =
     into(*newNames.map { it.name }.toTypedArray())
 
+/**
+ * Renames the columns selected with [rename] by applying the [transform] expression
+ * to each of them. This expression receives the column together with its full path
+ * (as [ColumnWithPath]) and must return the new name for that column.
+ * The operation preserves the original columns’ values and their positions within the [DataFrame].
+ *
+ * For more information: {@include [DocumentationUrls.Rename]}
+ *
+ * Check out [Grammar][RenameDocs.Grammar] for more details.
+ *
+ * ### Examples:
+ * ```kotlin
+ * // Rename all columns using their full path, delimited by "->"
+ * df.rename { colsAtAnyDepth() }.into { it.path.joinToString("->") }
+ *
+ * // Rename all `String` columns with uppercase
+ * df.rename { colsOf<String>() }.into { it.name.uppercase() }
+ * ```
+ *
+ * @param transform A function that takes a [ColumnWithPath] for each selected column
+ * and returns the new column name.
+ * @return A new [DataFrame] with the columns renamed.
+ */
 public fun <T, C> RenameClause<T, C>.into(transform: (ColumnWithPath<C>) -> String): DataFrame<T> =
     renameImpl(transform)
 
 /**
- * ## Rename to "camelCase"
- *
  * Renames the columns, previously selected with [rename] to "camelCase" format.
+ *
  * All delimiters between words are removed, words are capitalized except for the first one.
  * Places underscore between numbers.
  * If the string does not contain any letters or numbers, it remains unchanged.
@@ -214,7 +292,12 @@ public fun <T, C> RenameClause<T, C>.into(transform: (ColumnWithPath<C>) -> Stri
  * This function supports converting names from `snake_case`, `PascalCase`, and other delimited formats
  * into a consistent "camelCase" representation.
  *
- * ### Examples:
+ * ### Examples
+ * ```kotlin
+ * df.rename("arrival_date", "passport-ID").toCamelCase()
+ * ```
+ *
+ * #### Renaming Examples
  * ```
  * "snake_case_name" -> "snakeCaseName"
  * "PascalCaseName" -> "pascalCaseName"
@@ -233,7 +316,6 @@ public fun <T, C> RenameClause<T, C>.toCamelCase(): DataFrame<T> = into { it.ren
 // region DataColumn
 
 /**
- * ## Rename to camelCase
  *
  * Renames this column to "camelCase" format.
  * All delimiters between words are removed, words are capitalized except for the first one.
@@ -245,7 +327,7 @@ public fun <T, C> RenameClause<T, C>.toCamelCase(): DataFrame<T> = into { it.ren
  * This function supports converting names from `snake_case`, `PascalCase`, and other delimited formats
  * into a consistent "camelCase" representation.
  *
- * ### Examples:
+ * #### Renaming Examples
  * ```
  * "snake_case_name" -> "snakeCaseName"
  * "PascalCaseName" -> "pascalCaseName"
@@ -261,20 +343,44 @@ public fun <T, C : ColumnReference<T>> C.renameToCamelCase(): C =
     ) as C
 
 @Suppress("UNCHECKED_CAST")
+@AccessApiOverload
+@Deprecated(DEPRECATED_ACCESS_API)
 public fun <T, C : ColumnReference<T>> C.rename(column: KProperty<T>): C = rename(column.columnName) as C
 
 @Suppress("UNCHECKED_CAST")
+@AccessApiOverload
+@Deprecated(DEPRECATED_ACCESS_API)
 public fun <T, C : ColumnReference<T>> C.rename(column: ColumnAccessor<T>): C = rename(column.name()) as C
 
 // endregion
 
 // region named
 
+/**
+ * Returns a new column reference with the original column values but a new [name].
+ *
+ * This is useful when you want to specify an existing column
+ * (for example, in `select`, `update`, or `rename` operations)
+ * but give it a different name in the resulting [DataFrame].
+ *
+ * ### Example:
+ * ```kotlin
+ * // Select "size" column as "dimensions"
+ * df.select { size named "dimensions" }
+ * ```
+ *
+ * @param name The new name to assign to the column.
+ * @return A new column with the original structure and values but with the specified [name].
+ */
 @Suppress("UNCHECKED_CAST")
 public infix fun <T, C : ColumnReference<T>> C.named(name: String): C = rename(name) as C
 
+@AccessApiOverload
+@Deprecated(DEPRECATED_ACCESS_API)
 public infix fun <T, C : ColumnReference<T>> C.named(name: KProperty<*>): C = rename(name)
 
+@AccessApiOverload
+@Deprecated(DEPRECATED_ACCESS_API)
 public infix fun <T, C : ColumnReference<T>> C.named(name: ColumnAccessor<*>): C = rename(name)
 
 // endregion