Merge pull request #1683 from Kotlin/update-kdoc-helpers

Update kdoc helpers

Author: AndreiKingsley

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

@@ -36,7 +36,7 @@ public annotation class ColumnsSelectionDslMarker
 
 /**
  * ## Columns Selection DSL
- * {@include [SelectingColumns.Dsl.WithExample]}
+ * {@include [SelectingColumns.ColumnsSelectionDsl.ColumnsSelectionDslWithExample]}
  * {@set [SelectingColumns.OPERATION] [select][DataFrame.select]}
  *
  * @comment This interface be safely cast to [SingleColumn] across the library because it's always

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

@@ -18,7 +18,7 @@ import org.jetbrains.kotlinx.dataframe.documentation.DocumentationUrls
 import org.jetbrains.kotlinx.dataframe.documentation.ExcludeFromSources
 import org.jetbrains.kotlinx.dataframe.documentation.LineBreak
 import org.jetbrains.kotlinx.dataframe.documentation.NA
-import org.jetbrains.kotlinx.dataframe.documentation.NaN
+import org.jetbrains.kotlinx.dataframe.documentation.`NaN`
 import org.jetbrains.kotlinx.dataframe.documentation.SelectingColumns
 import org.jetbrains.kotlinx.dataframe.get
 import org.jetbrains.kotlinx.dataframe.typeClass
@@ -67,7 +67,7 @@ private typealias CommonFillNullsFunctionDoc = Nothing
 
 /**
  * @include [CommonFillNullsFunctionDoc]
- * @include [SelectingColumns.Dsl.WithExample] {@include [SetFillNullsOperationArg]}
+ * @include [SelectingColumns.ColumnsSelectionDsl.ColumnsSelectionDslWithExample] {@include [SetFillNullsOperationArg]}
  * @include [Update.DslParam]
  */
 @Interpretable("FillNulls0")
@@ -76,14 +76,14 @@ public fun <T, C> DataFrame<T>.fillNulls(columns: ColumnsSelector<T, C?>): Updat
 
 /**
  * @include [CommonFillNullsFunctionDoc]
- * @include [SelectingColumns.ColumnNames.WithExample] {@include [SetFillNullsOperationArg]}
+ * @include [SelectingColumns.ColumnNamesApi.ColumnNamesApiWithExample] {@include [SetFillNullsOperationArg]}
  * @include [Update.ColumnNamesParam]
  */
 public fun <T> DataFrame<T>.fillNulls(vararg columns: String): Update<T, Any?> = fillNulls { columns.toColumnSet() }
 
 /**
  * @include [CommonFillNullsFunctionDoc]
- * @include [SelectingColumns.KProperties.WithExample] {@include [SetFillNullsOperationArg]}
+ *
  * @include [Update.KPropertiesParam]
  */
 @Deprecated(DEPRECATED_ACCESS_API)
@@ -93,7 +93,7 @@ public fun <T, C> DataFrame<T>.fillNulls(vararg columns: KProperty<C>): Update<T
 
 /**
  * @include [CommonFillNullsFunctionDoc]
- * @include [SelectingColumns.ColumnAccessors.WithExample] {@include [SetFillNullsOperationArg]}
+ *
  * @include [Update.ColumnAccessorsParam]
  */
 @Deprecated(DEPRECATED_ACCESS_API)
@@ -140,7 +140,7 @@ internal inline val Any?.isNA: Boolean
 internal inline val AnyCol.canHaveNaN: Boolean get() = typeClass.let { it == Double::class || it == Float::class }
 
 /**
- * Is `true` when [this] column can have [NA] values.
+ * Is `true` when [this] column can have [`NA`] values.
  * @see NA
  */
 internal inline val AnyCol.canHaveNA: Boolean get() = hasNulls() || canHaveNaN || kind() != ColumnKind.Value
@@ -197,7 +197,7 @@ private typealias CommonFillNaNsFunctionDoc = Nothing
 
 /**
  * @include [CommonFillNaNsFunctionDoc]
- * @include [SelectingColumns.Dsl.WithExample] {@include [SetFillNaNsOperationArg]}
+ * @include [SelectingColumns.ColumnsSelectionDsl.ColumnsSelectionDslWithExample] {@include [SetFillNaNsOperationArg]}
  * @include [Update.DslParam]
  */
 @Interpretable("FillNaNs0")
@@ -206,14 +206,14 @@ public fun <T, C> DataFrame<T>.fillNaNs(columns: ColumnsSelector<T, C>): Update<
 
 /**
  * @include [CommonFillNaNsFunctionDoc]
- * @include [SelectingColumns.ColumnNames.WithExample] {@include [SetFillNaNsOperationArg]}
+ * @include [SelectingColumns.ColumnNamesApi.ColumnNamesApiWithExample] {@include [SetFillNaNsOperationArg]}
  * @include [Update.ColumnNamesParam]
  */
 public fun <T> DataFrame<T>.fillNaNs(vararg columns: String): Update<T, Any?> = fillNaNs { columns.toColumnSet() }
 
 /**
  * @include [CommonFillNaNsFunctionDoc]
- * @include [SelectingColumns.KProperties.WithExample] {@include [SetFillNaNsOperationArg]}
+ *
  * @include [Update.KPropertiesParam]
  */
 @Deprecated(DEPRECATED_ACCESS_API)
@@ -222,7 +222,7 @@ public fun <T, C> DataFrame<T>.fillNaNs(vararg columns: KProperty<C>): Update<T,
 
 /**
  * @include [CommonFillNaNsFunctionDoc]
- * @include [SelectingColumns.ColumnAccessors.WithExample] {@include [SetFillNaNsOperationArg]}
+ *
  * @include [Update.ColumnAccessorsParam]
  */
 @Deprecated(DEPRECATED_ACCESS_API)
@@ -272,7 +272,7 @@ private typealias CommonFillNAFunctionDoc = Nothing
 
 /**
  * @include [CommonFillNAFunctionDoc]
- * @include [SelectingColumns.Dsl.WithExample] {@include [SetFillNAOperationArg]}
+ * @include [SelectingColumns.ColumnsSelectionDsl.ColumnsSelectionDslWithExample] {@include [SetFillNAOperationArg]}
  * @include [Update.DslParam]
  */
 @Interpretable("FillNulls0") // fillNA changes schema same as fillNulls
@@ -281,14 +281,14 @@ public fun <T, C> DataFrame<T>.fillNA(columns: ColumnsSelector<T, C?>): Update<T
 
 /**
  * @include [CommonFillNAFunctionDoc]
- * @include [SelectingColumns.ColumnNames.WithExample] {@include [SetFillNAOperationArg]}
+ * @include [SelectingColumns.ColumnNamesApi.ColumnNamesApiWithExample] {@include [SetFillNAOperationArg]}
  * @include [Update.ColumnNamesParam]
  */
 public fun <T> DataFrame<T>.fillNA(vararg columns: String): Update<T, Any?> = fillNA { columns.toColumnSet() }
 
 /**
  * @include [CommonFillNAFunctionDoc]
- * @include [SelectingColumns.KProperties.WithExample] {@include [SetFillNAOperationArg]}
+ *
  * @include [Update.KPropertiesParam]
  */
 @Deprecated(DEPRECATED_ACCESS_API)
@@ -297,7 +297,7 @@ public fun <T, C> DataFrame<T>.fillNA(vararg columns: KProperty<C>): Update<T, C
 
 /**
  * @include [CommonFillNAFunctionDoc]
- * @include [SelectingColumns.ColumnAccessors.WithExample] {@include [SetFillNAOperationArg]}
+ *
  * @include [Update.ColumnAccessorsParam]
  */
 @Deprecated(DEPRECATED_ACCESS_API)
@@ -366,7 +366,7 @@ private typealias CommonDropNullsFunctionDoc = Nothing
 
 /**
  * @include [CommonDropNullsFunctionDoc]
- * @include [SelectingColumns.Dsl.WithExample] {@include [SetDropNullsOperationArg]}
+ * @include [SelectingColumns.ColumnsSelectionDsl.ColumnsSelectionDslWithExample] {@include [SetDropNullsOperationArg]}
  * `df.`[dropNulls][dropNulls]`(whereAllNull = true) { `[colsOf][colsOf]`<`[Double][Double]`>() }`
  * @include [DropNulls.WhereAllNullParam]
  * @include [DropDslParam]
@@ -402,7 +402,7 @@ public fun <T> DataFrame<T>.dropNulls(whereAllNull: Boolean = false): DataFrame<
 
 /**
  * @include [CommonDropNullsFunctionDoc]
- * @include [SelectingColumns.KProperties.WithExample] {@include [SetDropNullsOperationArg]}
+ *
  * `df.`[dropNulls][dropNulls]`(Person::length, whereAllNull = true)`
  * @include [DropNulls.WhereAllNullParam]
  * @include [DropKPropertiesParam]
@@ -414,7 +414,7 @@ public fun <T> DataFrame<T>.dropNulls(vararg columns: KProperty<*>, whereAllNull
 
 /**
  * @include [CommonDropNullsFunctionDoc]
- * @include [SelectingColumns.ColumnNames.WithExample] {@include [SetDropNullsOperationArg]}
+ *
  * `df.`[dropNulls][dropNulls]`("length", whereAllNull = true)`
  * @include [DropNulls.WhereAllNullParam]
  * @include [DropColumnNamesParam]
@@ -424,7 +424,7 @@ public fun <T> DataFrame<T>.dropNulls(vararg columns: String, whereAllNull: Bool
 
 /**
  * @include [CommonDropNullsFunctionDoc]
- * @include [SelectingColumns.ColumnAccessors.WithExample] {@include [SetDropNullsOperationArg]}
+ *
  * `df.`[dropNulls][dropNulls]`(length, whereAllNull = true)`
  * @include [DropNulls.WhereAllNullParam]
  * @include [DropColumnAccessorsParam]
@@ -487,7 +487,7 @@ private typealias CommonDropNAFunctionDoc = Nothing
 
 /**
  * @include [CommonDropNAFunctionDoc]
- * @include [SelectingColumns.Dsl.WithExample] {@include [SetDropNAOperationArg]}
+ * @include [SelectingColumns.ColumnsSelectionDsl.ColumnsSelectionDslWithExample] {@include [SetDropNAOperationArg]}
  * `df.`[dropNA][dropNA]`(whereAllNA = true) { `[colsOf][colsOf]`<`[Double][Double]`>() }`
  * @include [DropNA.WhereAllNAParam]
  * @include [DropDslParam]
@@ -505,7 +505,7 @@ public fun <T> DataFrame<T>.dropNA(whereAllNA: Boolean = false, columns: Columns
 
 /**
  * @include [CommonDropNAFunctionDoc]
- * @include [SelectingColumns.KProperties.WithExample] {@include [SetDropNAOperationArg]}
+ *
  * `df.`[dropNA][dropNA]`(Person::length, whereAllNA = true)`
  * @include [DropNA.WhereAllNAParam]
  * @include [DropKPropertiesParam]
@@ -517,7 +517,7 @@ public fun <T> DataFrame<T>.dropNA(vararg columns: KProperty<*>, whereAllNA: Boo
 
 /**
  * @include [CommonDropNAFunctionDoc]
- * @include [SelectingColumns.ColumnNames.WithExample] {@include [SetDropNAOperationArg]}
+ * @include [SelectingColumns.ColumnNamesApi.ColumnNamesApiWithExample] {@include [SetDropNAOperationArg]}
  * `df.`[dropNA][dropNA]`("length", whereAllNA = true)`
  * @include [DropNA.WhereAllNAParam]
  * @include [DropColumnNamesParam]
@@ -527,7 +527,7 @@ public fun <T> DataFrame<T>.dropNA(vararg columns: String, whereAllNA: Boolean =
 
 /**
  * @include [CommonDropNAFunctionDoc]
- * @include [SelectingColumns.ColumnAccessors.WithExample] {@include [SetDropNAOperationArg]}
+ *
  * `df.`[dropNA][dropNA]`(length, whereAllNA = true)`
  * @include [DropNA.WhereAllNAParam]
  * @include [DropColumnAccessorsParam]
@@ -602,7 +602,7 @@ private typealias CommonDropNaNsFunctionDoc = Nothing
 
 /**
  * @include [CommonDropNaNsFunctionDoc]
- * @include [SelectingColumns.Dsl.WithExample] {@include [SetDropNaNsOperationArg]}
+ * @include [SelectingColumns.ColumnsSelectionDsl.ColumnsSelectionDslWithExample] {@include [SetDropNaNsOperationArg]}
  * `df.`[dropNaNs][dropNaNs]`(whereAllNaN = true) { `[colsOf][colsOf]`<`[Double][Double]`>() }`
  * @include [DropNaNs.WhereAllNaNParam]
  * @include [DropDslParam]
@@ -618,7 +618,7 @@ public fun <T> DataFrame<T>.dropNaNs(whereAllNaN: Boolean = false, columns: Colu
 
 /**
  * @include [CommonDropNaNsFunctionDoc]
- * @include [SelectingColumns.KProperties.WithExample] {@include [SetDropNaNsOperationArg]}
+ *
  * `df.`[dropNaNs][dropNaNs]`(Person::length, whereAllNaN = true)`
  * @include [DropNaNs.WhereAllNaNParam]
  * @include [DropKPropertiesParam]
@@ -630,7 +630,7 @@ public fun <T> DataFrame<T>.dropNaNs(vararg columns: KProperty<*>, whereAllNaN:
 
 /**
  * @include [CommonDropNaNsFunctionDoc]
- * @include [SelectingColumns.ColumnNames.WithExample] {@include [SetDropNaNsOperationArg]}
+ *
  * `df.`[dropNaNs][dropNaNs]`("length", whereAllNaN = true)`
  * @include [DropNaNs.WhereAllNaNParam]
  * @include [DropColumnNamesParam]
@@ -640,7 +640,7 @@ public fun <T> DataFrame<T>.dropNaNs(vararg columns: String, whereAllNaN: Boolea
 
 /**
  * @include [CommonDropNaNsFunctionDoc]
- * @include [SelectingColumns.ColumnAccessors.WithExample] {@include [SetDropNaNsOperationArg]}
+ *
  * `df.`[dropNaNs][dropNaNs]`(length, whereAllNaN = true)`
  * @include [DropNaNs.WhereAllNaNParam]
  * @include [DropColumnAccessorsParam]

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

@@ -15,7 +15,6 @@ import org.jetbrains.kotlinx.dataframe.annotations.AccessApiOverload
 import org.jetbrains.kotlinx.dataframe.annotations.HasSchema
 import org.jetbrains.kotlinx.dataframe.annotations.Interpretable
 import org.jetbrains.kotlinx.dataframe.annotations.Refine
-import org.jetbrains.kotlinx.dataframe.api.add
 import org.jetbrains.kotlinx.dataframe.columns.BaseColumn
 import org.jetbrains.kotlinx.dataframe.columns.ColumnAccessor
 import org.jetbrains.kotlinx.dataframe.columns.ColumnPath
@@ -248,7 +247,7 @@ public inline fun <reified R, T> DataFrame<T>.add(
  * For more information: {@include [DocumentationUrls.Add]}.
  *
  * Returns a new [DataFrame] with the new column inserted at the given [path].
- * {@include [org.jetbrains.kotlinx.dataframe.documentation.ColumnPathCreation]}
+ * {@include [org.jetbrains.kotlinx.dataframe.documentation.ColumnPathCreationSnippet]}
  *
  * ## Example
  *

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

@@ -17,7 +17,7 @@ import org.jetbrains.kotlinx.dataframe.columns.ColumnWithPath
 import org.jetbrains.kotlinx.dataframe.columns.ColumnsResolver
 import org.jetbrains.kotlinx.dataframe.columns.SingleColumn
 import org.jetbrains.kotlinx.dataframe.columns.toColumnSet
-import org.jetbrains.kotlinx.dataframe.documentation.AccessApi.ExtensionPropertiesApiLink
+import org.jetbrains.kotlinx.dataframe.documentation.AccessApis.ExtensionPropertiesApiLink
 import org.jetbrains.kotlinx.dataframe.documentation.DslGrammarTemplateColumnsSelectionDsl.DslGrammarTemplate
 import org.jetbrains.kotlinx.dataframe.documentation.ExcludeFromSources
 import org.jetbrains.kotlinx.dataframe.documentation.Indent

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

@@ -30,7 +30,7 @@ public fun <T> DataColumn<T>.any(predicate: Predicate<T>): Boolean = values.any(
 /**
  * Returns `true` if at least one row in this [DataFrame] satisfies the given [predicate].
  *
- * {@include [org.jetbrains.kotlinx.dataframe.documentation.RowFilterDescription]}
+ * {@include [org.jetbrains.kotlinx.dataframe.documentation.SelectingRows.RowFilterSnippet]}
  *
  * ### Example
  * ```kotlin

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

@@ -3,7 +3,7 @@ package org.jetbrains.kotlinx.dataframe.api
 import org.jetbrains.kotlinx.dataframe.DataFrame
 import org.jetbrains.kotlinx.dataframe.DataRow
 import org.jetbrains.kotlinx.dataframe.RowExpression
-import org.jetbrains.kotlinx.dataframe.documentation.ExtensionPropertiesAPIDocs
+import org.jetbrains.kotlinx.dataframe.documentation.AccessApis
 
 // region DataFrame
 
@@ -13,7 +13,7 @@ import org.jetbrains.kotlinx.dataframe.documentation.ExtensionPropertiesAPIDocs
  *
  * The [transform] is a [RowExpression] — a lambda that receives each [DataRow]
  * both as `this` and `it` and is expected to return a key, allowing you to compute keys directly from row values.
- * You can also use [extension properties][ExtensionPropertiesAPIDocs] for concise and type-safe access.
+ * You can also use [extension properties][AccessApis.ExtensionPropertiesApi] for concise and type-safe access.
  *
  * If multiple rows produce the same key, the last row for that key is stored,
  * consistent with Kotlin's [kotlin.collections.associateBy] behavior.
@@ -39,7 +39,7 @@ public inline fun <T, V> DataFrame<T>.associateBy(transform: RowExpression<T, V>
  *
  * The [transform] is a [RowExpression] — a lambda that receives each [DataRow]
  * both as `this` and `it` and is expected to return a pair, allowing you to generate [Pair]s of keys and values from row contents.
- * You can also use [extension properties][ExtensionPropertiesAPIDocs] for concise and type-safe access.
+ * You can also use [extension properties][AccessApis.ExtensionPropertiesApi] for concise and type-safe access.
  *
  * If multiple rows produce the same key, the last value for that key is stored,
  * consistent with Kotlin's [kotlin.collections.associate] behavior.

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

@@ -11,7 +11,7 @@ import org.jetbrains.kotlinx.dataframe.columns.ColumnReference
 import org.jetbrains.kotlinx.dataframe.columns.ColumnSet
 import org.jetbrains.kotlinx.dataframe.columns.ColumnsResolver
 import org.jetbrains.kotlinx.dataframe.columns.SingleColumn
-import org.jetbrains.kotlinx.dataframe.documentation.AccessApi
+import org.jetbrains.kotlinx.dataframe.documentation.AccessApis
 import org.jetbrains.kotlinx.dataframe.documentation.DslGrammarTemplateColumnsSelectionDsl.DslGrammarTemplate
 import org.jetbrains.kotlinx.dataframe.documentation.Indent
 import org.jetbrains.kotlinx.dataframe.documentation.LineBreak
@@ -67,7 +67,7 @@ public interface ColGroupsColumnsSelectionDsl {
      * Creates a subset of columns from [this\] that are [ColumnGroups][ColumnGroup].
      *
      * You can optionally use a [filter\] to only include certain columns.
-     * [colGroups] can be called using any of the supported [APIs][AccessApi] (+ [ColumnPath]).
+     * [colGroups] can be called using any of the supported [APIs][AccessApis] (+ [ColumnPath]).
      *
      * This function operates solely on columns at the top-level.
      *

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

@@ -10,7 +10,7 @@ import org.jetbrains.kotlinx.dataframe.columns.ColumnReference
 import org.jetbrains.kotlinx.dataframe.columns.ColumnSet
 import org.jetbrains.kotlinx.dataframe.columns.ColumnsResolver
 import org.jetbrains.kotlinx.dataframe.columns.SingleColumn
-import org.jetbrains.kotlinx.dataframe.documentation.AccessApi
+import org.jetbrains.kotlinx.dataframe.documentation.AccessApis
 import org.jetbrains.kotlinx.dataframe.documentation.DslGrammarTemplateColumnsSelectionDsl.DslGrammarTemplate
 import org.jetbrains.kotlinx.dataframe.documentation.Indent
 import org.jetbrains.kotlinx.dataframe.documentation.LineBreak
@@ -71,7 +71,7 @@ public interface ColsOfKindColumnsSelectionDsl {
      * Creates a subset of columns from [this\] that are of the given kind(s).
      *
      * You can optionally use a [filter\] to only include certain columns.
-     * [colsOfKind] can be called using any of the supported [APIs][AccessApi] (+ [ColumnPath]).
+     * [colsOfKind] can be called using any of the supported [APIs][AccessApis] (+ [ColumnPath]).
      *
      * This function operates solely on columns at the top-level.
      *

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

@@ -22,7 +22,6 @@ import org.jetbrains.kotlinx.dataframe.annotations.Converter
 import org.jetbrains.kotlinx.dataframe.annotations.HasSchema
 import org.jetbrains.kotlinx.dataframe.annotations.Interpretable
 import org.jetbrains.kotlinx.dataframe.annotations.Refine
-import org.jetbrains.kotlinx.dataframe.api.convertToDeprecatedInstant
 import org.jetbrains.kotlinx.dataframe.columns.BaseColumn
 import org.jetbrains.kotlinx.dataframe.columns.ColumnGroup
 import org.jetbrains.kotlinx.dataframe.columns.ColumnReference
@@ -106,7 +105,7 @@ internal typealias SeeAlsoParse = Nothing
  *
  * Check out [Grammar].
  *
- * @include [SelectingColumns.ColumnGroupsAndNestedColumnsMention]
+ * @include [SelectingColumns.ColumnGroupsAndNestedColumnsSnippet]
  *
  * See [Selecting Columns][ConvertSelectingOptions].
  *
@@ -229,7 +228,7 @@ private typealias CommonConvertDocs = Nothing
 
 /**
  * @include [CommonConvertDocs]
- * @include [SelectingColumns.Dsl] {@include [SetConvertOperationArg]}
+ * @include [SelectingColumns.ColumnsSelectionDsl] {@include [SetConvertOperationArg]}
  * ### Examples:
  * ```kotlin
  * df.convert { columnA and columnB }.with { it.toString().lowercase() }
@@ -247,7 +246,7 @@ public fun <T, C> DataFrame<T>.convert(vararg columns: KProperty<C>): Convert<T,
 
 /**
  * @include [CommonConvertDocs]
- * @include [SelectingColumns.ColumnNames] {@include [SetConvertOperationArg]}
+ * @include [SelectingColumns.ColumnNamesApi] {@include [SetConvertOperationArg]}
  * ### Example:
  * ```kotlin
  * df.convert("person", "position").toStr()