convert kdocs fixes

AndreiKingsley · AndreiKingsley · commit 099c8e25170d · 2025-04-29T16:02:30.000+04:00
diff --git a/core/api/core.api b/core/api/core.api
@@ -1529,6 +1529,7 @@ public final class org/jetbrains/kotlinx/dataframe/api/ConvertKt {
 	public static final fun convertToStringFromT (Lorg/jetbrains/kotlinx/dataframe/DataColumn;)Lorg/jetbrains/kotlinx/dataframe/DataColumn;
 	public static final fun convertToURL (Lorg/jetbrains/kotlinx/dataframe/DataColumn;)Lorg/jetbrains/kotlinx/dataframe/DataColumn;
 	public static final fun convertToURLFromStringNullable (Lorg/jetbrains/kotlinx/dataframe/DataColumn;)Lorg/jetbrains/kotlinx/dataframe/DataColumn;
+	public static final fun to (Lorg/jetbrains/kotlinx/dataframe/api/Convert;Lkotlin/jvm/functions/Function2;)Lorg/jetbrains/kotlinx/dataframe/DataFrame;
 	public static final fun to (Lorg/jetbrains/kotlinx/dataframe/api/Convert;Lkotlin/reflect/KType;)Lorg/jetbrains/kotlinx/dataframe/DataFrame;
 	public static final fun toBigDecimal (Lorg/jetbrains/kotlinx/dataframe/api/Convert;)Lorg/jetbrains/kotlinx/dataframe/DataFrame;
 	public static final fun toBigDecimalTAny (Lorg/jetbrains/kotlinx/dataframe/api/Convert;)Lorg/jetbrains/kotlinx/dataframe/DataFrame;
diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/convert.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/convert.kt
@@ -6,12 +6,14 @@ import kotlinx.datetime.LocalDateTime
 import kotlinx.datetime.LocalTime
 import kotlinx.datetime.TimeZone
 import kotlinx.datetime.toLocalDateTime
+import org.jetbrains.kotlinx.dataframe.AnyBaseCol
 import org.jetbrains.kotlinx.dataframe.AnyCol
 import org.jetbrains.kotlinx.dataframe.AnyFrame
 import org.jetbrains.kotlinx.dataframe.ColumnsContainer
 import org.jetbrains.kotlinx.dataframe.ColumnsSelector
 import org.jetbrains.kotlinx.dataframe.DataColumn
 import org.jetbrains.kotlinx.dataframe.DataFrame
+import org.jetbrains.kotlinx.dataframe.DataFrameExpression
 import org.jetbrains.kotlinx.dataframe.DataRow
 import org.jetbrains.kotlinx.dataframe.RowColumnExpression
 import org.jetbrains.kotlinx.dataframe.RowValueExpression
@@ -46,6 +48,8 @@ import org.jetbrains.kotlinx.dataframe.impl.api.withRowCellImpl
 import org.jetbrains.kotlinx.dataframe.impl.headPlusArray
 import org.jetbrains.kotlinx.dataframe.impl.io.FastDoubleParser
 import org.jetbrains.kotlinx.dataframe.io.toDataFrame
+import org.jetbrains.kotlinx.dataframe.util.CONVERT_TO
+import org.jetbrains.kotlinx.dataframe.util.CONVERT_TO_REPLACE
 import java.math.BigDecimal
 import java.math.BigInteger
 import java.net.URL
@@ -79,8 +83,7 @@ internal interface SeeAlsoParse
  * Additionally, it offers a wide range of methods for converting to specific types,
  * such as [toStr][Convert.toStr], [toDouble][Convert.toDouble], and many others.
  *
- * For the full list of supported types,
- * refer to the [documentation website]({@include [DocumentationUrls.Url]}/convert.html).
+ * For the full list of supported types, see [SupportedTypes].
  *
  * Each method returns a new [DataFrame] with the updated columns.
  *
@@ -102,6 +105,18 @@ internal interface ConvertDocs {
      */
     interface ConvertSelectingOptions
 
+    /**
+     * List of types, supported in [convert to][Convert.to] operation:
+     * * [String] (uses parse to convert from String to other types);
+     * * [Boolean];
+     * * [Byte], [Short], [Char];
+     * * [Int], [Long], [Float], [Double];
+     * * [BigDecimal], [BigInteger];
+     * * [LocalDateTime], [LocalDate], [LocalTime], [Instant] ( (kotlinx.datetime and [java.time]),
+     * * [URL], [IMG], [IFRAME].
+     */
+    interface SupportedTypes
+
     /**
      * ## Convert Operation Grammar
      * {@include [LineBreak]}
@@ -123,9 +138,6 @@ internal interface ConvertDocs {
      * `| `__`.`__[**`to`**][Convert.to]`(type: `[`KType`][KType]`)`
      *
      * {@include [Indent]}
-     * `| `__`.`__[**`to`**][Convert.to]`  { columnConverter: `[`DataFrame`](DataFrame)`.(`[`DataColumn`](DataColumn)`) -> `[`AnyBaseColumn`](AnyBaseColumn)`  }`
-     *
-     * {@include [Indent]}
      * `| `__`.`__[**`perRowCol`**][Convert.perRowCol]`  { expression: `[`RowColumnExpression`][RowColumnExpression]`  }`
      *
      * {@include [Indent]}
@@ -293,7 +305,7 @@ public inline fun <T, C, reified R> Convert<T, C?>.notNull(
  *
  * Use the following methods to perform the conversion:
  * - [to(kType)][to]/[to`<Type`>()][to] – converts columns to a specific type.
- * - [to { columnConverter }][to] - converts columns using column converter expression.
+ * - [asColumn { columnConverter }][asColumn] - converts columns using column converter expression.
  * - [with][Convert.with] – applies a custom row-wise conversion expression.
  * - [notNull][Convert.notNull] – like [with], but only for non-null values.
  * - [perRowCol][Convert.perRowCol] – applies a conversion that uses both column and row information.
@@ -324,8 +336,7 @@ public class Convert<T, out C>(
      * preserving their original names and positions within the [DataFrame].
      *
      * The target type is provided as a reified type argument.
-     * For the full list of supported types,
-     * refer to the [documentation website]({@include [DocumentationUrls.Url]}/convert.html).
+     * For the full list of supported types, see [ConvertDocs.SupportedTypes].
      *
      * For more information: {@include [DocumentationUrls.Convert]}
      *
@@ -353,8 +364,7 @@ public class Convert<T, out C>(
  * preserving their original names and positions within the [DataFrame].
  *
  * The target type is provided as a [KType].
- * For the full list of supported types,
- * refer to the [documentation website]({@include [DocumentationUrls.Url]}/convert.html).
+ * For the full list of supported types, see [ConvertDocs.SupportedTypes].
  *
  * For more information: {@include [DocumentationUrls.Convert]}
  *
@@ -372,6 +382,10 @@ public class Convert<T, out C>(
  */
 public fun <T> Convert<T, *>.to(type: KType): DataFrame<T> = asColumn { it.convertTo(type) }
 
+@Deprecated(CONVERT_TO, ReplaceWith(CONVERT_TO_REPLACE), DeprecationLevel.ERROR)
+public fun <T, C> Convert<T, C>.to(columnConverter: DataFrame<T>.(DataColumn<C>) -> AnyBaseCol): DataFrame<T> =
+    df.replace(columns).with { columnConverter(df, it) }
+
 /** [Convert per row col][Convert.perRowCol] to provide a new value for every selected cell giving its column. */
 @ExcludeFromSources
 private interface SeeAlsoConvertPerRowCol
@@ -512,8 +526,7 @@ public inline fun <T, C, reified R> Convert<T, C>.perRowCol(
  *
  * The target type is provided as a reified type argument.
  *
- * For the full list of supported types,
- * refer to the [documentation website]({@include [DocumentationUrls.Url]}/convert.html).
+ * For the full list of supported types, see [ConvertDocs.SupportedTypes].
  *
  * @param [C] The target type to convert values to.
  * @return A new [DataColumn] with the values converted to type [C].
@@ -523,8 +536,7 @@ public inline fun <reified C> AnyCol.convertTo(): DataColumn<C> = convertTo(type
 /**
  * Converts values in this column to the specified [type].
  *
- * For the full list of supported types,
- * refer to the [documentation website]({@include [DocumentationUrls.Url]}/convert.html).
+ * For the full list of supported types, see [ConvertDocs.SupportedTypes].
  *
  * @param type The target type, provided as a [KType], to convert values to.
  * @return A new [DataColumn] with the values converted to [type].
diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/replace.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/replace.kt
@@ -55,7 +55,7 @@ public fun <T, C> ReplaceClause<T, C>.with(newColumns: List<AnyCol>): DataFrame<
 // TODO: Issue #418: breaks if running on ColumnGroup and its child
 
 /**
- * For an alternative supported in the compiler plugin use [Convert.to]
+ * For an alternative supported in the compiler plugin use [Convert.asColumn]
  */
 public fun <T, C> ReplaceClause<T, C>.with(transform: ColumnsContainer<T>.(DataColumn<C>) -> AnyBaseCol): DataFrame<T> {
     val removeResult = df.removeImpl(columns = columns)
diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/impl/api/parse.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/impl/api/parse.kt
@@ -18,7 +18,6 @@ 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.to
 import org.jetbrains.kotlinx.dataframe.api.asColumnGroup
 import org.jetbrains.kotlinx.dataframe.api.asDataColumn
 import org.jetbrains.kotlinx.dataframe.api.cast
diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/util/deprecationMessages.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/util/deprecationMessages.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
