diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/ColumnsSelectionDsl.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/ColumnsSelectionDsl.kt index c1cb3db256..bd4aa1122d 100644 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/ColumnsSelectionDsl.kt +++ b/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 diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/Nulls.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/Nulls.kt index bb5a5e65bf..6bf6aa7d59 100644 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/Nulls.kt +++ b/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 DataFrame.fillNulls(columns: ColumnsSelector): Updat /** * @include [CommonFillNullsFunctionDoc] - * @include [SelectingColumns.ColumnNames.WithExample] {@include [SetFillNullsOperationArg]} + * @include [SelectingColumns.ColumnNamesApi.ColumnNamesApiWithExample] {@include [SetFillNullsOperationArg]} * @include [Update.ColumnNamesParam] */ public fun DataFrame.fillNulls(vararg columns: String): Update = fillNulls { columns.toColumnSet() } /** * @include [CommonFillNullsFunctionDoc] - * @include [SelectingColumns.KProperties.WithExample] {@include [SetFillNullsOperationArg]} + * * @include [Update.KPropertiesParam] */ @Deprecated(DEPRECATED_ACCESS_API) @@ -93,7 +93,7 @@ public fun DataFrame.fillNulls(vararg columns: KProperty): Update DataFrame.fillNaNs(columns: ColumnsSelector): Update< /** * @include [CommonFillNaNsFunctionDoc] - * @include [SelectingColumns.ColumnNames.WithExample] {@include [SetFillNaNsOperationArg]} + * @include [SelectingColumns.ColumnNamesApi.ColumnNamesApiWithExample] {@include [SetFillNaNsOperationArg]} * @include [Update.ColumnNamesParam] */ public fun DataFrame.fillNaNs(vararg columns: String): Update = fillNaNs { columns.toColumnSet() } /** * @include [CommonFillNaNsFunctionDoc] - * @include [SelectingColumns.KProperties.WithExample] {@include [SetFillNaNsOperationArg]} + * * @include [Update.KPropertiesParam] */ @Deprecated(DEPRECATED_ACCESS_API) @@ -222,7 +222,7 @@ public fun DataFrame.fillNaNs(vararg columns: KProperty): Update DataFrame.fillNA(columns: ColumnsSelector): Update DataFrame.fillNA(vararg columns: String): Update = fillNA { columns.toColumnSet() } /** * @include [CommonFillNAFunctionDoc] - * @include [SelectingColumns.KProperties.WithExample] {@include [SetFillNAOperationArg]} + * * @include [Update.KPropertiesParam] */ @Deprecated(DEPRECATED_ACCESS_API) @@ -297,7 +297,7 @@ public fun DataFrame.fillNA(vararg columns: KProperty): Update() }` * @include [DropNulls.WhereAllNullParam] * @include [DropDslParam] @@ -402,7 +402,7 @@ public fun DataFrame.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 DataFrame.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 DataFrame.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 DataFrame.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 DataFrame.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 DataFrame.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 DataFrame.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 DataFrame.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 DataFrame.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] diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/add.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/add.kt index be53cf9f46..8fdd94da4e 100644 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/add.kt +++ b/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 DataFrame.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 * diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/allExcept.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/allExcept.kt index 2db9bae5f0..1d9a7b5c42 100644 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/allExcept.kt +++ b/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 diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/any.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/any.kt index 1f7902f5d2..b6fb2993ff 100644 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/any.kt +++ b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/any.kt @@ -30,7 +30,7 @@ public fun DataColumn.any(predicate: Predicate): 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 diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/associate.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/associate.kt index 1a3264187b..e1a3d9d5a0 100644 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/associate.kt +++ b/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 DataFrame.associateBy(transform: RowExpression * * 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. diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/colGroups.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/colGroups.kt index 8597b11bd5..a1cbca71de 100644 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/colGroups.kt +++ b/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. * diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/colsOfKind.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/colsOfKind.kt index 436d9c81ec..bfe654f01d 100644 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/colsOfKind.kt +++ b/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. * 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 index 360cdefb0e..eb8da54d60 100644 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/convert.kt +++ b/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 DataFrame.convert(vararg columns: KProperty): Convert DataFrame.corr(): DataFrame = /** * {@include [CommonCorrDocs]} - * @include [SelectingColumns.Dsl] {@include [SetCorrOperationArg]} + * @include [SelectingColumns.ColumnsSelectionDsl] {@include [SetCorrOperationArg]} * * The function is available for numeric- and [Boolean] columns. * [Boolean] values are converted into 1 for true and 0 for false. @@ -162,7 +162,7 @@ public fun DataFrame.corr(columns: ColumnsSelector): Corr /** * {@include [CommonCorrDocs]} - * @include [SelectingColumns.ColumnNames] {@include [SetCorrOperationArg]} + * @include [SelectingColumns.ColumnNamesApi] {@include [SetCorrOperationArg]} * * The function is available for numeric- and [Boolean] columns. * [Boolean] values are converted into 1 for true and 0 for false. @@ -202,7 +202,7 @@ public fun DataFrame.corr(vararg columns: ColumnReference): Corr Corr.with(otherColumns: ColumnsSelector): DataF /** * {@include [CommonCorrWithDocs]} - * @include [SelectingColumns.ColumnNames] {@include [SetCorrOperationArg]} + * @include [SelectingColumns.ColumnNamesApi] {@include [SetCorrOperationArg]} * * ### Examples * ```kotlin diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/count.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/count.kt index 5acaf176d3..c8237a374b 100644 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/count.kt +++ b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/count.kt @@ -9,7 +9,7 @@ import org.jetbrains.kotlinx.dataframe.RowFilter import org.jetbrains.kotlinx.dataframe.annotations.Interpretable import org.jetbrains.kotlinx.dataframe.annotations.Refine import org.jetbrains.kotlinx.dataframe.documentation.DocumentationUrls -import org.jetbrains.kotlinx.dataframe.documentation.RowFilterDescription +import org.jetbrains.kotlinx.dataframe.documentation.SelectingRows import org.jetbrains.kotlinx.dataframe.impl.aggregation.modes.aggregateValue // region DataColumn @@ -70,7 +70,7 @@ public fun DataFrame.count(): Int = rowsCount() /** * Counts the number of rows in this [DataFrame] that satisfy the given [predicate]. * - * {@include [RowFilterDescription]} + * {@include [SelectingRows.RowFilterSnippet]} * * See also: * - [filter][DataFrame.filter] — filters rows using a [RowFilter] condition. @@ -130,7 +130,7 @@ public fun Grouped.count(resultName: String = "count"): DataFrame = * Aggregates this [GroupBy] by counting the number of rows in each group * that satisfy the given [predicate]. * - * {@include [RowFilterDescription]} + * {@include [SelectingRows.RowFilterSnippet]} * * Returns a new [DataFrame] where each row corresponds to a group. * The resulting frame contains: @@ -204,7 +204,7 @@ public fun Pivot.count(): DataRow = delegate { count() } * Aggregates this [Pivot] by counting the number of rows in each group * that satisfy the given [predicate]. * - * {@include [RowFilterDescription]} + * {@include [SelectingRows.RowFilterSnippet]} * * Returns a single [DataRow] where: * - each column corresponds to a [pivot] group — if multiple pivot keys were used, diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/countDistinct.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/countDistinct.kt index 7b29a19de5..5b2b949606 100644 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/countDistinct.kt +++ b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/countDistinct.kt @@ -50,7 +50,7 @@ internal typealias CountDistinctDocs = Nothing /** * {@include [CountDistinctDocs]} - * {@include [SelectingColumns.Dsl]} + * {@include [SelectingColumns.ColumnsSelectionDsl]} * * #### Example * @@ -69,7 +69,7 @@ public fun DataFrame.countDistinct(columns: ColumnsSelector): In /** * {@include [CountDistinctDocs]} - * {@include [SelectingColumns.ColumnNames]} + * {@include [SelectingColumns.ColumnNamesApi]} * * #### Example * diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/describe.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/describe.kt index fe5160131d..3d73991a98 100644 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/describe.kt +++ b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/describe.kt @@ -125,7 +125,8 @@ public fun DataFrame.describe(): DataFrame = /** * @include [DescribeWithSelection] - * @include [SelectingColumns.Dsl.WithExample] {@include [SetDescribeOperationArg]} + * @include [SelectingColumns.ColumnsSelectionDsl.ColumnsSelectionDslWithExample] {@include [SetDescribeOperationArg]} + * * @param [columns] The [Columns Selector][ColumnsSelector] that specifies which * columns of this [DataFrame] should be described. */ @@ -134,7 +135,8 @@ public fun DataFrame.describe(columns: ColumnsSelector): DataFrame< /** * @include [DescribeWithSelection] - * @include [SelectingColumns.ColumnNames.WithExample] {@include [SetDescribeOperationArg]} + * @include [SelectingColumns.ColumnNamesApi.ColumnNamesApiWithExample] {@include [SetDescribeOperationArg]} + * * @param [columns] The [Column Names][String] that specifies which * columns of this [DataFrame] should be described. */ @@ -143,7 +145,7 @@ public fun DataFrame.describe(vararg columns: String): DataFrame DataFrame.describe(vararg columns: ColumnReferenc /** * @include [DescribeWithSelection] - * @include [SelectingColumns.KProperties.WithExample] {@include [SetDescribeOperationArg]} + * * @param [columns] The [KProperties][KProperty] that specifies which * columns of this [DataFrame] should be described. */ diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/distinct.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/distinct.kt index 396005bd7d..4ad440456e 100644 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/distinct.kt +++ b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/distinct.kt @@ -37,7 +37,7 @@ import kotlin.reflect.KProperty * See also {@get [SEE_ALSO] [distinctBy] that removes duplicated rows based on the specified columns * and keeps all the columns in the resulting [DataFrame].} * - * @include [SelectingColumns.ColumnGroupsAndNestedColumnsMention] + * @include [SelectingColumns.ColumnGroupsAndNestedColumnsSnippet] * * See [Selecting Columns][SelectSelectingOptions]. * diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/drop.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/drop.kt index 4df60c8007..a967e40496 100644 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/drop.kt +++ b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/drop.kt @@ -18,7 +18,6 @@ import org.jetbrains.kotlinx.dataframe.documentation.CommonTakeAndDropWhileDocs import org.jetbrains.kotlinx.dataframe.documentation.TakeAndDropColumnsSelectionDslGrammar import org.jetbrains.kotlinx.dataframe.impl.columns.transform import org.jetbrains.kotlinx.dataframe.impl.columns.transformSingle -import org.jetbrains.kotlinx.dataframe.index import org.jetbrains.kotlinx.dataframe.nrow import org.jetbrains.kotlinx.dataframe.util.DEPRECATED_ACCESS_API import kotlin.reflect.KProperty diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/explode.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/explode.kt index a127fa0d0d..657fbae02b 100644 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/explode.kt +++ b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/explode.kt @@ -41,7 +41,7 @@ private val defaultExplodeColumns: ColumnsSelector<*, *> = { * * This operation is the reverse of [implode]. * - * @include [SelectingColumns.ColumnGroupsAndNestedColumnsMention] + * @include [SelectingColumns.ColumnGroupsAndNestedColumnsSnippet] * * For more information, see: {@include [DocumentationUrls.Explode]} * @@ -52,7 +52,7 @@ internal typealias ExplodeDocs = Nothing /** * {@include [ExplodeDocs]} - * {@include [SelectingColumns.Dsl]} + * {@include [SelectingColumns.ColumnsSelectionDsl]} * * #### Examples * @@ -82,7 +82,7 @@ public fun DataFrame.explode( /** * {@include [ExplodeDocs]} - * {@include [SelectingColumns.ColumnNames]} + * {@include [SelectingColumns.ColumnNamesApi]} * * #### Example * @@ -132,7 +132,7 @@ public fun DataFrame.explode(vararg columns: KProperty, dropEmpty: * Each exploded column will have a new type (`List` → `T`). * When several columns are exploded in one operation, lists in different columns will be aligned. * - * @include [SelectingColumns.ColumnGroupsAndNestedColumnsMention] + * @include [SelectingColumns.ColumnGroupsAndNestedColumnsSnippet] * * For more information, see: {@include [DocumentationUrls.Explode]} * @@ -143,7 +143,7 @@ internal typealias ExplodeDataRowDocs = Nothing /** * {@include [ExplodeDataRowDocs]} - * {@include [SelectingColumns.Dsl]} + * {@include [SelectingColumns.ColumnsSelectionDsl]} * * #### Example * @@ -166,7 +166,7 @@ public fun DataRow.explode( /** * {@include [ExplodeDataRowDocs]} - * {@include [SelectingColumns.ColumnNames]} + * {@include [SelectingColumns.ColumnNamesApi]} * * #### Example * diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/expr.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/expr.kt index 27965a5d8f..38e9cd3a88 100644 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/expr.kt +++ b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/expr.kt @@ -1,6 +1,5 @@ package org.jetbrains.kotlinx.dataframe.api -import org.jetbrains.kotlinx.dataframe.ColumnsContainer import org.jetbrains.kotlinx.dataframe.DataColumn import org.jetbrains.kotlinx.dataframe.DataFrame import org.jetbrains.kotlinx.dataframe.annotations.Interpretable @@ -46,8 +45,6 @@ public interface ExprColumnsSelectionDsl { /** * @include [ColumnExpression.CommonDocs] * - * This function is essentially a shortcut for [ColumnsContainer.mapToColumn]. - * * ### Check out: [Usage][ExprColumnsSelectionDsl.Grammar] * * #### For example: @@ -59,7 +56,6 @@ public interface ExprColumnsSelectionDsl { * @param [name] The name the temporary column. Is empty by default ("untitled" in the DataFrame). * @include [Infer.ParamDoc] By default: [Nulls][Infer.Nulls]. * @param [expression] An [AddExpression] to define what each new row of the temporary column should contain. - * @see [ColumnsContainer.mapToColumn] */ @Interpretable("Expr0") public inline fun ColumnsSelectionDsl.expr( diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/filter.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/filter.kt index b98e9577f4..04f064feeb 100644 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/filter.kt +++ b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/filter.kt @@ -18,8 +18,8 @@ import org.jetbrains.kotlinx.dataframe.documentation.DocumentationUrls import org.jetbrains.kotlinx.dataframe.documentation.DslGrammarTemplateColumnsSelectionDsl.DslGrammarTemplate import org.jetbrains.kotlinx.dataframe.documentation.Indent import org.jetbrains.kotlinx.dataframe.documentation.LineBreak -import org.jetbrains.kotlinx.dataframe.documentation.RowFilterDescription import org.jetbrains.kotlinx.dataframe.documentation.SelectingColumns +import org.jetbrains.kotlinx.dataframe.documentation.SelectingRows import org.jetbrains.kotlinx.dataframe.impl.getTrueIndices import org.jetbrains.kotlinx.dataframe.indices import org.jetbrains.kotlinx.dataframe.util.DEPRECATED_ACCESS_API @@ -48,9 +48,9 @@ public inline fun DataColumn.filter(predicate: Predicate): DataColumn< * Filters the rows of this [DataFrame] based on the provided [RowFilter]. * Returns a new [DataFrame] containing only the rows that satisfy the given [predicate]. * - * {@include [RowFilterDescription]} + * {@include [SelectingRows.RowFilterSnippet]} * - * @include [SelectingColumns.ColumnGroupsAndNestedColumnsMention] + * @include [SelectingColumns.ColumnGroupsAndNestedColumnsSnippet] * * For more information, see: {@include [DocumentationUrls.Filter]} * diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/first.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/first.kt index de1f5f570d..c3b9572c16 100644 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/first.kt +++ b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/first.kt @@ -19,8 +19,8 @@ import org.jetbrains.kotlinx.dataframe.documentation.DocumentationUrls import org.jetbrains.kotlinx.dataframe.documentation.DslGrammarTemplateColumnsSelectionDsl.DslGrammarTemplate import org.jetbrains.kotlinx.dataframe.documentation.Indent import org.jetbrains.kotlinx.dataframe.documentation.LineBreak -import org.jetbrains.kotlinx.dataframe.documentation.RowFilterDescription import org.jetbrains.kotlinx.dataframe.documentation.SelectingColumns +import org.jetbrains.kotlinx.dataframe.documentation.SelectingRows import org.jetbrains.kotlinx.dataframe.impl.columns.TransformableColumnSet import org.jetbrains.kotlinx.dataframe.impl.columns.singleOrNullWithTransformerImpl import org.jetbrains.kotlinx.dataframe.impl.columns.transform @@ -139,9 +139,9 @@ public fun DataFrame.firstOrNull(): DataRow? = if (nrow > 0) first() e /** * Returns the first [row][DataRow] in this [DataFrame] that satisfies the given [predicate]. * - * @include [RowFilterDescription] + * @include [SelectingRows.RowFilterSnippet] * - * @include [SelectingColumns.ColumnGroupsAndNestedColumnsMention] + * @include [SelectingColumns.ColumnGroupsAndNestedColumnsSnippet] * * ### Example * ```kotlin @@ -173,9 +173,9 @@ public inline fun DataFrame.first(predicate: RowFilter): DataRow = * Returns `null` if the [DataFrame] contains no rows matching the [predicate] * (including the case when the [DataFrame] is empty). * - * @include [RowFilterDescription] + * @include [SelectingRows.RowFilterSnippet] * - * @include [SelectingColumns.ColumnGroupsAndNestedColumnsMention] + * @include [SelectingColumns.ColumnGroupsAndNestedColumnsSnippet] * * ### Example * ```kotlin @@ -241,9 +241,9 @@ public fun GroupBy.first(): ReducedGroupBy = reduce { firstOr * the corresponding row in [ReducedGroupBy] will contain `null` values for all columns in the group, * except the grouping key. * - * @include [RowFilterDescription] + * @include [SelectingRows.RowFilterSnippet] * - * @include [SelectingColumns.ColumnGroupsAndNestedColumnsMention] + * @include [SelectingColumns.ColumnGroupsAndNestedColumnsSnippet] * * ### Example * ```kotlin @@ -293,9 +293,9 @@ public fun Pivot.first(): ReducedPivot = reduce { firstOrNull() } * * For more information about [Pivot] with examples: {@include [DocumentationUrls.Pivot]} * - * @include [RowFilterDescription] + * @include [SelectingRows.RowFilterSnippet] * - * @include [SelectingColumns.ColumnGroupsAndNestedColumnsMention] + * @include [SelectingColumns.ColumnGroupsAndNestedColumnsSnippet] * * ### Example * ```kotlin @@ -361,9 +361,9 @@ public fun PivotGroupBy.first(): ReducedPivotGroupBy = reduce { firstO * * @include [DocumentationUrls.GroupBy] * - * @include [RowFilterDescription] + * @include [SelectingRows.RowFilterSnippet] * - * @include [SelectingColumns.ColumnGroupsAndNestedColumnsMention] + * @include [SelectingColumns.ColumnGroupsAndNestedColumnsSnippet] * * ### Example * ```kotlin diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/format.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/format.kt index 58149fedb4..3a29a2deb1 100644 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/format.kt +++ b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/format.kt @@ -57,7 +57,7 @@ import kotlin.reflect.KProperty * This function does not immediately produce a [FormattedFrame], but instead it selects the columns to be formatted * and returns a [FormatClause] which serves as an intermediate step. * - * @include [SelectingColumns.ColumnGroupsAndNestedColumnsMention] + * @include [SelectingColumns.ColumnGroupsAndNestedColumnsSnippet] * * See [Selecting Columns][FormatSelectingColumns]. * @@ -238,7 +238,7 @@ private typealias CommonFormatDocs = Nothing /** * @include [CommonFormatDocs] - * @include [SelectingColumns.Dsl] {@include [SetFormatOperationArg]} + * @include [SelectingColumns.ColumnsSelectionDsl] {@include [SetFormatOperationArg]} * ### Examples: * ```kt * df.format { temperature }.linearBg(-20 to FormattingDsl.blue, 50 to FormattingDsl.red) @@ -256,7 +256,7 @@ public fun DataFrame.format(columns: ColumnsSelector): FormatCla /** * @include [CommonFormatDocs] - * @include [SelectingColumns.ColumnNames] {@include [SetFormatOperationArg]} + * @include [SelectingColumns.ColumnNamesApi] {@include [SetFormatOperationArg]} * ### Examples: * ```kt * df.format("temperature").with { linearBg(it as Number, -20 to blue, 50 to red) } @@ -308,7 +308,7 @@ public fun DataFrame.format(vararg columns: KProperty): FormatClaus /** * @include [CommonFormatDocs] - * @include [SelectingColumns.Dsl] {@include [SetFormatOperationArg]} + * @include [SelectingColumns.ColumnsSelectionDsl] {@include [SetFormatOperationArg]} * ### Examples: * ```kt * df.format().with { background(white) and textColor(black) and bold } @@ -328,7 +328,7 @@ public fun FormattedFrame.format(columns: ColumnsSelector): Form /** * @include [CommonFormatDocs] - * @include [SelectingColumns.ColumnNames] {@include [SetFormatOperationArg]} + * @include [SelectingColumns.ColumnNamesApi] {@include [SetFormatOperationArg]} * ### Examples: * ```kt * df.format("temperature").with { linearBg(it as Number, -20 to blue, 50 to red) } diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/frameCols.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/frameCols.kt index af902bd472..0b26ee5e87 100644 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/frameCols.kt +++ b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/frameCols.kt @@ -12,7 +12,7 @@ import org.jetbrains.kotlinx.dataframe.columns.ColumnSet import org.jetbrains.kotlinx.dataframe.columns.ColumnsResolver import org.jetbrains.kotlinx.dataframe.columns.FrameColumn 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 @@ -70,7 +70,7 @@ public interface FrameColsColumnsSelectionDsl { * Creates a subset of columns from [this\] that are [FrameColumns][FrameColumn]. * * You can optionally use a [filter\] to only include certain columns. - * [frameCols] can be called using any of the supported [APIs][AccessApi] (+ [ColumnPath]). + * [frameCols] can be called using any of the supported [APIs][AccessApis] (+ [ColumnPath]). * * This function operates solely on columns at the top-level. * diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/gather.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/gather.kt index f2f931f643..cc417f9c4b 100644 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/gather.kt +++ b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/gather.kt @@ -52,7 +52,7 @@ import kotlin.reflect.typeOf * * This operation is the reverse of [pivot]. * - * @include [SelectingColumns.ColumnGroupsAndNestedColumnsMention] + * @include [SelectingColumns.ColumnGroupsAndNestedColumnsSnippet] * * For more information: {@include [DocumentationUrls.Gather]} * @@ -111,7 +111,7 @@ private typealias CommonGatherDocs = Nothing /** * @include [CommonGatherDocs] - * @include [SelectingColumns.Dsl] {@include [SetGatherOperationArg]} + * @include [SelectingColumns.ColumnsSelectionDsl] {@include [SetGatherOperationArg]} * ### Examples * ```kotlin * // Gather `resultA` and `resultB` columns into a single "value" column, @@ -138,7 +138,7 @@ public fun DataFrame.gather(selector: ColumnsSelector): Gather DataFrame.group(columns: ColumnsSelector): GroupClaus /** * @include [CommonGroupDocs] - * @include [SelectingColumns.ColumnNames] {@include [SetGroupOperationArg]} + * @include [SelectingColumns.ColumnNamesApi] {@include [SetGroupOperationArg]} * ### Example: * ```kotlin * df.group("second").into("valueCols") @@ -160,7 +160,7 @@ public class GroupClause(internal val df: DataFrame, internal val colum * * For more information: {@include [DocumentationUrls.Group]} * - * @include [SelectingColumns.ColumnNames] + * @include [SelectingColumns.ColumnNamesApi] * * ### Example: * ```kotlin @@ -184,13 +184,13 @@ public fun GroupClause.into(column: ColumnsSelectionDsl.(ColumnW * Groups columns, previously selected with [group], into a new or existing column group * within the [DataFrame] by specifying its path via [ColumnsSelectionDsl] expression. * - * {@include [org.jetbrains.kotlinx.dataframe.documentation.ColumnPathCreation]} + * {@include [org.jetbrains.kotlinx.dataframe.documentation.ColumnPathCreationSnippet]} * * See [Selecting Columns][SelectingColumns]. * * For more information: {@include [DocumentationUrls.Group]} * - * @include [SelectingColumns.Dsl] + * @include [SelectingColumns.ColumnsSelectionDsl] * * ### Examples: * ```kotlin @@ -223,7 +223,7 @@ public fun GroupClause.into( * * For more information: {@include [DocumentationUrls.Group]} * - * @include [SelectingColumns.ColumnNames] + * @include [SelectingColumns.ColumnNamesApi] * * ### Examples: * ```kotlin diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/groupBy.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/groupBy.kt index 40f464d5cb..56dae3eb3f 100644 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/groupBy.kt +++ b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/groupBy.kt @@ -54,7 +54,7 @@ import kotlin.reflect.KProperty * * Check out [Grammar]. * - * @include [SelectingColumns.ColumnGroupsAndNestedColumnsMention] + * @include [SelectingColumns.ColumnGroupsAndNestedColumnsSnippet] * * See [Selecting Columns][GroupBySelectingOptions]. * @@ -346,7 +346,7 @@ private typealias CommonGroupByDocs = Nothing /** * @include [CommonGroupByDocs] - * @include [SelectingColumns.Dsl.WithExample] {@include [SetGroupByOperationArg]} + * @include [SelectingColumns.ColumnsSelectionDsl.ColumnsSelectionDslWithExample] {@include [SetGroupByOperationArg]} * * @param [moveToTop] Specifies whether nested grouping columns should be moved to the top level * or kept inside a [ColumnGroup][org.jetbrains.kotlinx.dataframe.columns.ColumnGroup]. @@ -367,7 +367,7 @@ public fun DataFrame.groupBy(vararg cols: KProperty<*>): GroupBy = /** * @include [CommonGroupByDocs] - * @include [SelectingColumns.ColumnNames.WithExample] {@include [SetGroupByOperationArg]} + * @include [SelectingColumns.ColumnNamesApi.ColumnNamesApiWithExample] {@include [SetGroupByOperationArg]} * * @param [cols] The [Column names][String] that defines which columns are used * as keys for grouping. @@ -405,7 +405,7 @@ private typealias CommonGroupByForPivotDocs = Nothing /** * {@include [CommonGroupByForPivotDocs]} - * @include [SelectingColumns.Dsl.WithExample] {@include [SetGroupByOperationArg] {@set [SelectingColumns.RECEIVER] `pivot`}} + * @include [SelectingColumns.ColumnsSelectionDsl.ColumnsSelectionDslWithExample] {@include [SetGroupByOperationArg] {@set [SelectingColumns.RECEIVER] `pivot`}} * * @param moveToTop Specifies whether nested grouping columns should be moved to the top level * or kept inside a [ColumnGroup][org.jetbrains.kotlinx.dataframe.columns.ColumnGroup]. @@ -424,7 +424,7 @@ public fun Pivot.groupBy(vararg columns: AnyColumnReference): PivotGroupB /** * {@include [CommonGroupByForPivotDocs]} - * @include [SelectingColumns.ColumnNames] + * @include [SelectingColumns.ColumnNamesApi] * * #### For example: * diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/insert.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/insert.kt index 2df51e87af..a8a175d551 100644 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/insert.kt +++ b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/insert.kt @@ -43,7 +43,7 @@ import kotlin.reflect.KProperty * * Check out [Grammar]. * - * @include [SelectingColumns.ColumnGroupsAndNestedColumnsMention] + * @include [SelectingColumns.ColumnGroupsAndNestedColumnsSnippet] * * See [Selecting Columns][InsertSelectingOptions]. * @@ -197,7 +197,7 @@ public class InsertClause(internal val df: DataFrame, internal val column: * * See [Grammar][InsertDocs.Grammar] for more details. * - * See [SelectingColumns.Dsl]. + * See [SelectingColumns.ColumnsSelectionDsl]. * * ### Examples * ```kotlin @@ -220,7 +220,7 @@ public fun InsertClause.under(column: ColumnSelector): DataFrame * Inserts the new column previously specified with [insert] under * the column group defined by the given [columnPath]. * - * {@include [org.jetbrains.kotlinx.dataframe.documentation.ColumnPathCreation]} + * {@include [org.jetbrains.kotlinx.dataframe.documentation.ColumnPathCreationSnippet]} * * See [Grammar][InsertDocs.Grammar] for more details. * @@ -285,7 +285,7 @@ public fun InsertClause.under(column: String): DataFrame = under(pathO * * See [Grammar][InsertDocs.Grammar] for more details. * - * See also: [SelectingColumns.Dsl]. + * See {@include [SelectingColumns.CSDslSingleLink]}. * * ### Examples: * ```kotlin @@ -312,7 +312,7 @@ public fun InsertClause.after(column: ColumnSelector): DataFrame * * See [Grammar][InsertDocs.Grammar] for more details. * - * See also: [SelectingColumns.ColumnNames]. + * See also: [SelectingColumns.ColumnNamesApi]. * * ### Example * ```kotlin @@ -352,7 +352,7 @@ public fun InsertClause.after(columnPath: ColumnPath): DataFrame { * * See [Grammar][InsertDocs.Grammar] for more details. * - * See also: [SelectingColumns.Dsl]. + * See also: [SelectingColumns.ColumnsSelectionDsl]. * * ### Examples: * ```kotlin @@ -379,7 +379,7 @@ public fun InsertClause.before(column: ColumnSelector): DataFrame DataFrame.join( * See also general [join], as well as other shortcuts with each of join types: * [leftJoin], [rightJoin], [fullJoin], [filterJoin], [excludeJoin]. * - * @include [SelectingColumns.ColumnGroupsAndNestedColumnsMention] + * @include [SelectingColumns.ColumnGroupsAndNestedColumnsSnippet] * * See [Selecting Columns][SelectingColumns]. * @@ -184,7 +185,7 @@ public fun DataFrame.innerJoin( /** * @include [InnerJoinDocs] - * @include [SelectingColumns.ColumnNames] + * @include [SelectingColumns.ColumnNamesApi] * @include [JoinStringApiExample] {@set [JOIN_METHOD] innerJoin} * @param other [DataFrame] to join with. * @param columns [Column Names][String] specifying join columns. @@ -205,7 +206,7 @@ public fun DataFrame.innerJoin(other: DataFrame, vararg columns: St * See also general [join], as well as other shortcuts with each of join types: * [innerJoin], [rightJoin], [fullJoin], [filterJoin], [excludeJoin]. * - * @include [SelectingColumns.ColumnGroupsAndNestedColumnsMention] + * @include [SelectingColumns.ColumnGroupsAndNestedColumnsSnippet] * * See [Selecting Columns][SelectingColumns]. * @@ -233,7 +234,7 @@ public fun DataFrame.leftJoin( /** * @include [LeftJoinDocs] - * @include [SelectingColumns.ColumnNames] + * @include [SelectingColumns.ColumnNamesApi] * @include [JoinStringApiExample] {@set [JOIN_METHOD] leftJoin} * @param other [DataFrame] to join with. * @param columns [Column Names][String] specifying join columns. @@ -254,7 +255,7 @@ public fun DataFrame.leftJoin(other: DataFrame, vararg columns: Str * See also general [join], as well as other shortcuts with each of join types: * [innerJoin], [leftJoin], [fullJoin], [filterJoin], [excludeJoin]. * - * @include [SelectingColumns.ColumnGroupsAndNestedColumnsMention] + * @include [SelectingColumns.ColumnGroupsAndNestedColumnsSnippet] * * See [Selecting Columns][SelectingColumns]. * @@ -282,7 +283,7 @@ public fun DataFrame.rightJoin( /** * @include [RightJoinDocs] - * @include [SelectingColumns.ColumnNames] + * @include [SelectingColumns.ColumnNamesApi] * @include [JoinStringApiExample] {@set [JOIN_METHOD] rightJoin} * @param other [DataFrame] to join with. * @param columns [Column Names][String] specifying join columns. @@ -303,7 +304,7 @@ public fun DataFrame.rightJoin(other: DataFrame, vararg columns: St * See also general [join], as well as other shortcuts with each of join types: * [innerJoin], [leftJoin], [rightJoin], [filterJoin], [excludeJoin]. * - * @include [SelectingColumns.ColumnGroupsAndNestedColumnsMention] + * @include [SelectingColumns.ColumnGroupsAndNestedColumnsSnippet] * * See [Selecting Columns][SelectingColumns]. * @@ -331,7 +332,7 @@ public fun DataFrame.fullJoin( /** * @include [FullJoinDocs] - * @include [SelectingColumns.ColumnNames] + * @include [SelectingColumns.ColumnNamesApi] * @include [JoinStringApiExample] {@set [JOIN_METHOD] fullJoin} * @param other [DataFrame] to join with. * @param columns [Column Names][String] specifying join columns. @@ -352,7 +353,7 @@ public fun DataFrame.fullJoin(other: DataFrame, vararg columns: Str * See also general [join], as well as other shortcuts with each of join types: * [innerJoin], [leftJoin], [rightJoin], [fullJoin], [excludeJoin]. * - * @include [SelectingColumns.ColumnGroupsAndNestedColumnsMention] + * @include [SelectingColumns.ColumnGroupsAndNestedColumnsSnippet] * * See [Selecting Columns][SelectingColumns]. * @@ -380,7 +381,7 @@ public fun DataFrame.filterJoin( /** * @include [FilterJoinDocs] - * @include [SelectingColumns.ColumnNames] + * @include [SelectingColumns.ColumnNamesApi] * @include [JoinStringApiExample] {@set [JOIN_METHOD] filterJoin} * @param other [DataFrame] to join with. * @param columns [Column Names][String] specifying join columns. @@ -401,7 +402,7 @@ public fun DataFrame.filterJoin(other: DataFrame, vararg columns: S * See also general [join], as well as other shortcuts with each of join types: * [innerJoin], [leftJoin], [rightJoin], [filterJoin], [fullJoin]. * - * @include [SelectingColumns.ColumnGroupsAndNestedColumnsMention] + * @include [SelectingColumns.ColumnGroupsAndNestedColumnsSnippet] * * See [Selecting Columns][SelectingColumns]. * @@ -429,7 +430,7 @@ public fun DataFrame.excludeJoin( /** * @include [ExcludeJoinDocs] - * @include [SelectingColumns.ColumnNames] + * @include [SelectingColumns.ColumnNamesApi] * @include [JoinStringApiExample] {@set [JOIN_METHOD] excludeJoin} * @param other [DataFrame] to join with. * @param columns [Column Names][String] specifying join columns. diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/joinWith.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/joinWith.kt index ee3a9f8076..29fb10a7c9 100644 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/joinWith.kt +++ b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/joinWith.kt @@ -90,7 +90,7 @@ public typealias JoinExpression = Selector, Boolean> * * See also [join], which performs a join by exact value equality in the selected columns. * - * @include [SelectingColumns.ColumnGroupsAndNestedColumnsMention] + * @include [SelectingColumns.ColumnGroupsAndNestedColumnsSnippet] * * For more information, {@include [DocumentationUrls.JoinWith]}. * @@ -121,7 +121,7 @@ public fun DataFrame.joinWith( * * See also [join], which performs a join by exact value equality in the selected columns. * - * @include [SelectingColumns.ColumnGroupsAndNestedColumnsMention] + * @include [SelectingColumns.ColumnGroupsAndNestedColumnsSnippet] * * For more information, {@include [DocumentationUrls.JoinWith]}. * @@ -148,7 +148,7 @@ public fun DataFrame.innerJoinWith(right: DataFrame, joinExpression * * See also [join], which performs a join by exact value equality in the selected columns. * - * @include [SelectingColumns.ColumnGroupsAndNestedColumnsMention] + * @include [SelectingColumns.ColumnGroupsAndNestedColumnsSnippet] * * For more information, {@include [DocumentationUrls.JoinWith]}. * @@ -175,7 +175,7 @@ public fun DataFrame.leftJoinWith(right: DataFrame, joinExpression: * * See also [join], which performs a join by exact value equality in the selected columns. * - * @include [SelectingColumns.ColumnGroupsAndNestedColumnsMention] + * @include [SelectingColumns.ColumnGroupsAndNestedColumnsSnippet] * * For more information, {@include [DocumentationUrls.JoinWith]}. * @@ -202,7 +202,7 @@ public fun DataFrame.rightJoinWith(right: DataFrame, joinExpression * * See also [join], which performs a join by exact value equality in the selected columns. * - * @include [SelectingColumns.ColumnGroupsAndNestedColumnsMention] + * @include [SelectingColumns.ColumnGroupsAndNestedColumnsSnippet] * * For more information, {@include [DocumentationUrls.JoinWith]}. * @@ -229,7 +229,7 @@ public fun DataFrame.fullJoinWith(right: DataFrame, joinExpression: * * See also [join], which performs a join by exact value equality in the selected columns. * - * @include [SelectingColumns.ColumnGroupsAndNestedColumnsMention] + * @include [SelectingColumns.ColumnGroupsAndNestedColumnsSnippet] * * For more information, {@include [DocumentationUrls.JoinWith]}. * @@ -256,7 +256,7 @@ public fun DataFrame.filterJoinWith(right: DataFrame, joinExpressio * * See also [join], which performs a join by exact value equality in the selected columns. * - * @include [SelectingColumns.ColumnGroupsAndNestedColumnsMention] + * @include [SelectingColumns.ColumnGroupsAndNestedColumnsSnippet] * * For more information, {@include [DocumentationUrls.JoinWith]}. * diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/last.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/last.kt index aa75a34d20..91867977e8 100644 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/last.kt +++ b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/last.kt @@ -19,8 +19,8 @@ import org.jetbrains.kotlinx.dataframe.documentation.DocumentationUrls import org.jetbrains.kotlinx.dataframe.documentation.DslGrammarTemplateColumnsSelectionDsl.DslGrammarTemplate import org.jetbrains.kotlinx.dataframe.documentation.Indent import org.jetbrains.kotlinx.dataframe.documentation.LineBreak -import org.jetbrains.kotlinx.dataframe.documentation.RowFilterDescription import org.jetbrains.kotlinx.dataframe.documentation.SelectingColumns +import org.jetbrains.kotlinx.dataframe.documentation.SelectingRows import org.jetbrains.kotlinx.dataframe.impl.columns.TransformableColumnSet import org.jetbrains.kotlinx.dataframe.impl.columns.singleOrNullWithTransformerImpl import org.jetbrains.kotlinx.dataframe.impl.columns.transform @@ -108,9 +108,9 @@ public inline fun DataColumn.lastOrNull(predicate: (T) -> Boolean): T? = * Returns `null` if the [DataFrame] contains no rows matching the [predicate] * (including the case when the [DataFrame] is empty). * - * @include [RowFilterDescription] + * @include [SelectingRows.RowFilterSnippet] * - * @include [SelectingColumns.ColumnGroupsAndNestedColumnsMention] + * @include [SelectingColumns.ColumnGroupsAndNestedColumnsSnippet] * * ### Example * ```kotlin @@ -138,9 +138,9 @@ public inline fun DataFrame.lastOrNull(predicate: RowFilter): DataRow< /** * Returns the last [row][DataRow] in this [DataFrame] that satisfies the given [predicate]. * - * @include [RowFilterDescription] + * @include [SelectingRows.RowFilterSnippet] * - * @include [SelectingColumns.ColumnGroupsAndNestedColumnsMention] + * @include [SelectingColumns.ColumnGroupsAndNestedColumnsSnippet] * * ### Example * ```kotlin @@ -237,9 +237,9 @@ public fun GroupBy.last(): ReducedGroupBy = reduce { lastOrNu * the corresponding row in [ReducedGroupBy] will contain `null` values for all columns in the group, * except the grouping key. * - * @include [RowFilterDescription] + * @include [SelectingRows.RowFilterSnippet] * - * @include [SelectingColumns.ColumnGroupsAndNestedColumnsMention] + * @include [SelectingColumns.ColumnGroupsAndNestedColumnsSnippet] * * ### Example * ```kotlin @@ -289,9 +289,9 @@ public fun Pivot.last(): ReducedPivot = reduce { lastOrNull() } * * For more information about [Pivot] with examples: {@include [DocumentationUrls.Pivot]} * - * @include [RowFilterDescription] + * @include [SelectingRows.RowFilterSnippet] * - * @include [SelectingColumns.ColumnGroupsAndNestedColumnsMention] + * @include [SelectingColumns.ColumnGroupsAndNestedColumnsSnippet] * * ### Example * ```kotlin @@ -358,9 +358,9 @@ public fun PivotGroupBy.last(): ReducedPivotGroupBy = reduce { lastOrN * * @include [DocumentationUrls.GroupBy] * - * @include [RowFilterDescription] + * @include [SelectingRows.RowFilterSnippet] * - * @include [SelectingColumns.ColumnGroupsAndNestedColumnsMention] + * @include [SelectingColumns.ColumnGroupsAndNestedColumnsSnippet] * * ### Example * ```kotlin diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/move.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/move.kt index ab54a3a6ec..67f14a8648 100644 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/move.kt +++ b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/move.kt @@ -49,7 +49,7 @@ import kotlin.reflect.KProperty * [after][MoveClause.after] or [under][MoveClause.under], that return a new [DataFrame] with updated columns structure. * Check out [Grammar]. * - * @include [SelectingColumns.ColumnGroupsAndNestedColumnsMention] + * @include [SelectingColumns.ColumnGroupsAndNestedColumnsSnippet] * * See [Selecting Columns][MoveSelectingOptions]. * @@ -111,7 +111,7 @@ private typealias CommonMoveDocs = Nothing /** * @include [CommonMoveDocs] - * @include [SelectingColumns.Dsl] {@include [SetMoveOperationArg]} + * @include [SelectingColumns.ColumnsSelectionDsl] {@include [SetMoveOperationArg]} * ### Examples: * ```kotlin * df.move { columnA and columnB }.after { columnC } @@ -125,7 +125,7 @@ public fun DataFrame.move(columns: ColumnsSelector): MoveClause< /** * @include [CommonMoveDocs] - * @include [SelectingColumns.ColumnNames] {@include [SetMoveOperationArg]} + * @include [SelectingColumns.ColumnNamesApi] {@include [SetMoveOperationArg]} * ### Examples: * ```kotlin * df.move("columnA", "columnB").after("columnC") @@ -154,7 +154,7 @@ public fun DataFrame.move(vararg columns: KProperty): MoveClause DataFrame.moveTo(newColumnIndex: Int, columns: ColumnsSelector /** * @include [CommonMoveToDocs] - * @include [SelectingColumns.ColumnNames] {@include [SetMoveToOperationArg]} + * @include [SelectingColumns.ColumnNamesApi] {@include [SetMoveToOperationArg]} * ### Examples: * ```kotlin * df.moveTo(0) { length and age } @@ -228,7 +228,7 @@ public fun DataFrame.moveTo(newColumnIndex: Int, vararg columns: KPropert * else they will be moved to the top level. * * @include [CommonMoveToDocs] - * @include [SelectingColumns.Dsl] {@include [SetMoveToOperationArg]} + * @include [SelectingColumns.ColumnsSelectionDsl] {@include [SetMoveToOperationArg]} * ### Examples: * ```kotlin * df.moveTo(0, true) { length and age } @@ -255,7 +255,7 @@ public fun DataFrame.moveTo( * else they will be moved to the top level. * * @include [CommonMoveToDocs] - * @include [SelectingColumns.ColumnNames] {@include [SetMoveToOperationArg]} + * @include [SelectingColumns.ColumnNamesApi] {@include [SetMoveToOperationArg]} * ### Examples: * ```kotlin * df.moveTo(0, true) { length and age } @@ -278,7 +278,7 @@ public fun DataFrame.moveTo(newColumnIndex: Int, insideGroup: Boolean, va * Moves the specified [columns\] to the [DataFrame] start (on top-level). * Returns a new [DataFrame] with updated columns structure. * - * @include [SelectingColumns.ColumnGroupsAndNestedColumnsMention] + * @include [SelectingColumns.ColumnGroupsAndNestedColumnsSnippet] * * See [Selecting Columns][MoveToStartSelectingOptions]. * @@ -308,7 +308,7 @@ public fun DataFrame.moveToLeft(columns: ColumnsSelector): DataFram /** * @include [CommonMoveToStartDocs] - * @include [SelectingColumns.Dsl.WithExample] {@include [SetMoveToStartOperationArg]} + * @include [SelectingColumns.ColumnsSelectionDsl.ColumnsSelectionDslWithExample] {@include [SetMoveToStartOperationArg]} * @param [columns\] The [Columns Selector][ColumnsSelector] used to select the columns of this [DataFrame] to move. */ @Refine @@ -317,7 +317,7 @@ public fun DataFrame.moveToStart(columns: ColumnsSelector): DataFra /** * @include [CommonMoveToStartDocs] - * @include [SelectingColumns.Dsl.WithExample] {@include [SetMoveToStartOperationArg]} + * @include [SelectingColumns.ColumnsSelectionDsl.ColumnsSelectionDslWithExample] {@include [SetMoveToStartOperationArg]} * @param [columns\] The [Columns Selector][ColumnsSelector] used to select the columns of this [DataFrame] to move. * @param [insideGroup] If true, selected columns will be moved to the start remaining inside their group, * else they will be moved to the start of the top level. @@ -332,14 +332,14 @@ public fun DataFrame.moveToLeft(vararg columns: String): DataFrame = m /** * @include [CommonMoveToStartDocs] - * @include [SelectingColumns.ColumnNames.WithExample] {@include [SetMoveToStartOperationArg]} + * @include [SelectingColumns.ColumnNamesApi.ColumnNamesApiWithExample] {@include [SetMoveToStartOperationArg]} * @param [columns\] The [Columns Selector][ColumnsSelector] used to select the columns of this [DataFrame] to move. */ public fun DataFrame.moveToStart(vararg columns: String): DataFrame = moveToStart { columns.toColumnSet() } /** * @include [CommonMoveToStartDocs] - * @include [SelectingColumns.ColumnNames.WithExample] {@include [SetMoveToStartOperationArg]} + * @include [SelectingColumns.ColumnNamesApi.ColumnNamesApiWithExample] {@include [SetMoveToStartOperationArg]} * @param [columns\] The [Columns Selector][ColumnsSelector] used to select the columns of this [DataFrame] to move. * @param [insideGroup] If true, selected columns will be moved to the start remaining inside their group, * else they will be moved to the start of the top level. @@ -375,7 +375,7 @@ public fun DataFrame.moveToStart(vararg columns: KProperty<*>): DataFrame * Moves the specified [columns\] to the [DataFrame] end. * Returns a new [DataFrame] with updated columns structure. * - * @include [SelectingColumns.ColumnGroupsAndNestedColumnsMention] + * @include [SelectingColumns.ColumnGroupsAndNestedColumnsSnippet] * * See [Selecting Columns][MoveToEndSelectingOptions]. * @@ -405,7 +405,7 @@ public fun DataFrame.moveToRight(columns: ColumnsSelector): DataFra /** * @include [CommonMoveToEndDocs] - * @include [SelectingColumns.Dsl.WithExample] {@include [SetMoveToEndOperationArg]} + * @include [SelectingColumns.ColumnsSelectionDsl.ColumnsSelectionDslWithExample] {@include [SetMoveToEndOperationArg]} * @param [columns\] The [Columns Selector][ColumnsSelector] used to select the columns of this [DataFrame] to move. */ @Refine @@ -414,7 +414,7 @@ public fun DataFrame.moveToEnd(columns: ColumnsSelector): DataFrame /** * @include [CommonMoveToEndDocs] - * @include [SelectingColumns.Dsl.WithExample] {@include [SetMoveToEndOperationArg]} + * @include [SelectingColumns.ColumnsSelectionDsl.ColumnsSelectionDslWithExample] {@include [SetMoveToEndOperationArg]} * @param [columns\] The [Columns Selector][ColumnsSelector] used to select the columns of this [DataFrame] to move. * @param [insideGroup] If true, selected columns will be moved to the end remaining inside their group, * else they will be moved to the end of the top level. @@ -429,14 +429,14 @@ public fun DataFrame.moveToRight(vararg columns: String): DataFrame = /** * @include [CommonMoveToEndDocs] - * @include [SelectingColumns.ColumnNames.WithExample] {@include [SetMoveToEndOperationArg]} + * @include [SelectingColumns.ColumnNamesApi.ColumnNamesApiWithExample] {@include [SetMoveToEndOperationArg]} * @param [columns\] The [Columns Selector][ColumnsSelector] used to select the columns of this [DataFrame] to move. */ public fun DataFrame.moveToEnd(vararg columns: String): DataFrame = moveToEnd { columns.toColumnSet() } /** * @include [CommonMoveToEndDocs] - * @include [SelectingColumns.ColumnNames.WithExample] {@include [SetMoveToEndOperationArg]} + * @include [SelectingColumns.ColumnNamesApi.ColumnNamesApiWithExample] {@include [SetMoveToEndOperationArg]} * @param [columns\] The [Columns Selector][ColumnsSelector] used to select the columns of this [DataFrame] to move. * @param [insideGroup] If true, selected columns will be moved to the end remaining inside their group, * else they will be moved to the end of the top level. @@ -475,13 +475,13 @@ public fun DataFrame.moveToEnd(vararg columns: KProperty<*>): DataFrame MoveClause.into(column: String): DataFrame = pathOf(c * given column path within the [DataFrame]. * Provides selected column indices. * - * {@include [org.jetbrains.kotlinx.dataframe.documentation.ColumnPathCreation]} + * {@include [org.jetbrains.kotlinx.dataframe.documentation.ColumnPathCreationSnippet]} * * See [Selecting Columns][SelectingColumns]. * * For more information: {@include [DocumentationUrls.Move]} * - * @include [SelectingColumns.Dsl] + * @include [SelectingColumns.ColumnsSelectionDsl] * * ### Examples: * ```kotlin @@ -564,7 +564,7 @@ public fun MoveClause.intoIndexed( * * For more information: {@include [DocumentationUrls.Move]} * - * @include [SelectingColumns.ColumnNames] + * @include [SelectingColumns.ColumnNamesApi] * * ### Examples: * ```kotlin @@ -589,13 +589,13 @@ public fun MoveClause.under(column: AnyColumnGroupAccessor): DataFr * an existing column group specified by a * column path within the [DataFrame]. * - * {@include [org.jetbrains.kotlinx.dataframe.documentation.ColumnPathCreation]} + * {@include [org.jetbrains.kotlinx.dataframe.documentation.ColumnPathCreationSnippet]} * * See [Selecting Columns][SelectingColumns]. * * For more information: {@include [DocumentationUrls.Move]} * - * @include [SelectingColumns.Dsl] + * @include [SelectingColumns.ColumnsSelectionDsl] * * ### Examples: * ```kotlin @@ -715,7 +715,7 @@ internal typealias MoveAfter = Nothing /** * {@include [MoveAfter]} - * @include [SelectingColumns.Dsl] + * @include [SelectingColumns.ColumnsSelectionDsl] * * ### Examples: * ```kotlin @@ -732,7 +732,7 @@ public fun MoveClause.after(column: ColumnSelector): DataFram /** * {@include [MoveAfter]} - * @include [SelectingColumns.ColumnNames] + * @include [SelectingColumns.ColumnNamesApi] * * ### Examples: * ```kotlin @@ -772,7 +772,7 @@ internal typealias MoveBefore = Nothing /** * {@include [MoveBefore]} - * @include [SelectingColumns.Dsl] + * @include [SelectingColumns.ColumnsSelectionDsl] * * ### Examples: * ```kotlin @@ -789,7 +789,7 @@ public fun MoveClause.before(column: ColumnSelector): DataFra /** * {@include [MoveBefore]} - * @include [SelectingColumns.ColumnNames] + * @include [SelectingColumns.ColumnNamesApi] * * ### Examples: * ```kotlin diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/none.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/none.kt index 9124153145..51b958b6ee 100644 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/none.kt +++ b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/none.kt @@ -23,7 +23,7 @@ public fun DataColumn.none(predicate: Predicate): Boolean = values.non /** * Returns `true` if none of the rows in this [DataFrame] satisfies the given [predicate]. * - * {@include [org.jetbrains.kotlinx.dataframe.documentation.RowFilterDescription]} + * {@include [org.jetbrains.kotlinx.dataframe.documentation.SelectingRows.RowFilterSnippet]} * * ### Example * ```kotlin diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/pivot.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/pivot.kt index 5c78b3f729..de3da4b34e 100644 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/pivot.kt +++ b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/pivot.kt @@ -25,6 +25,7 @@ import org.jetbrains.kotlinx.dataframe.documentation.ExcludeFromSources import org.jetbrains.kotlinx.dataframe.documentation.Indent import org.jetbrains.kotlinx.dataframe.documentation.LineBreak import org.jetbrains.kotlinx.dataframe.documentation.SelectingColumns +import org.jetbrains.kotlinx.dataframe.documentation.SelectingColumns.CSDslLink import org.jetbrains.kotlinx.dataframe.impl.aggregation.PivotGroupByImpl import org.jetbrains.kotlinx.dataframe.impl.aggregation.PivotImpl import org.jetbrains.kotlinx.dataframe.impl.aggregation.PivotInAggregateImpl @@ -52,7 +53,7 @@ import kotlin.reflect.KProperty * * Check out [Grammar]. * - * @include [SelectingColumns.ColumnGroupsAndNestedColumnsMention] + * @include [SelectingColumns.ColumnGroupsAndNestedColumnsSnippet] * * See [Selecting Columns][SelectingColumns]. * @@ -359,7 +360,7 @@ public interface PivotDsl : ColumnsSelectionDsl { * with nested [column groups][ColumnGroup], representing a hierarchical structure of * keys combinations from the pivoted columns — i.e., one group per unique key combination. * - * See [Columns Selection via DSL][SelectingColumns.Dsl]. + * See {@include [CSDslLink]}. * * ### Examples * ```kotlin @@ -402,7 +403,7 @@ public fun DataFrame.pivot(inward: Boolean? = null, columns: PivotColumns /** * @include [CommonPivotDocs] - * @include [SelectingColumns.ColumnNames] + * @include [SelectingColumns.ColumnNamesApi] * * [pivot] with a single key column produces a [Pivot] containing one column for each unique key * (i.e., key column unique values) with the corresponding group; * * [pivot] with multiple keys combined using [and] produces a [Pivot] @@ -466,7 +467,7 @@ internal typealias PivotMatchesResultCellDescription = Nothing * This function combines [pivot][DataFrame.pivot], [groupByOther][Pivot.groupByOther], * and [matches][PivotGroupBy.matches] operations into a single call. * - * @include [SelectingColumns.ColumnGroupsAndNestedColumnsMention] + * @include [SelectingColumns.ColumnGroupsAndNestedColumnsSnippet] * * See [Selecting Columns][SelectSelectingOptions]. * @@ -506,7 +507,7 @@ public fun DataFrame.pivotMatches(inward: Boolean = true, columns: PivotC /** * @include [DataFramePivotMatchesCommonDocs] - * @include [SelectingColumns.ColumnNames] + * @include [SelectingColumns.ColumnNamesApi] * * ### Example * ```kotlin @@ -560,7 +561,7 @@ internal typealias PivotCountsResultCellDescription = Nothing * This function combines [pivot][DataFrame.pivot], [groupByOther][Pivot.groupByOther], * and [count][PivotGroupBy.count] operations into a single call. * - * @include [SelectingColumns.ColumnGroupsAndNestedColumnsMention] + * @include [SelectingColumns.ColumnGroupsAndNestedColumnsSnippet] * * See [Selecting Columns][SelectSelectingOptions]. * @@ -598,7 +599,7 @@ public fun DataFrame.pivotCounts(inward: Boolean = true, columns: PivotCo /** * @include [DataFramePivotCountsCommonDocs] - * @include [SelectingColumns.ColumnNames] + * @include [SelectingColumns.ColumnNamesApi] * * ### Example * ```kotlin @@ -654,7 +655,7 @@ private typealias CommonPivotForGroupByDocs = Nothing /** * @include [CommonPivotForGroupByDocs] - * @include [SelectingColumns.Dsl.WithExample] {@include [SetPivotOperationArg] {@set [SelectingColumns.RECEIVER] `gb`}} + * @include [SelectingColumns.ColumnsSelectionDsl.ColumnsSelectionDslWithExample] {@include [SetPivotOperationArg] {@set [SelectingColumns.RECEIVER] `gb`}} * @include [PivotDocs.InwardKDocsForGrouped] * @param [columns] The [Pivot Columns Selector][PivotColumnsSelector] that defines which columns are pivoted. * @return A new [PivotGroupBy] that preserves the original [groupBy] key columns @@ -670,7 +671,7 @@ public fun GroupBy<*, G>.pivot(vararg columns: AnyColumnReference, inward: B /** * @include [CommonPivotForGroupByDocs] - * @include [SelectingColumns.Dsl.WithExample] {@include [SetPivotOperationArg] {@set [SelectingColumns.RECEIVER] `gb`}} + * @include [SelectingColumns.ColumnsSelectionDsl.ColumnsSelectionDslWithExample] {@include [SetPivotOperationArg] {@set [SelectingColumns.RECEIVER] `gb`}} * @include [PivotDocs.InwardKDocsForGrouped] * @param [columns] The [Column names][String] that defines which columns are pivoted. * @return A new [PivotGroupBy] that preserves the original [groupBy] key columns @@ -699,7 +700,7 @@ public fun GroupBy<*, G>.pivot(vararg columns: KProperty<*>, inward: Boolean * This function combines [pivot][GroupBy.pivot] * and [matches][PivotGroupBy.matches] operations into a single call. * - * @include [SelectingColumns.ColumnGroupsAndNestedColumnsMention] + * @include [SelectingColumns.ColumnGroupsAndNestedColumnsSnippet] * * See [Selecting Columns][SelectSelectingOptions]. * @@ -735,7 +736,7 @@ public fun GroupBy<*, G>.pivotMatches(inward: Boolean = true, columns: Pivot /** * @include [GroupByPivotMatchesCommonDocs] - * @include [SelectingColumns.ColumnNames] + * @include [SelectingColumns.ColumnNamesApi] * * ### Example * ```kotlin @@ -775,7 +776,7 @@ public fun GroupBy<*, G>.pivotMatches(vararg columns: KProperty<*>, inward: * This function combines [pivot][GroupBy.pivot] * and [count][PivotGroupBy.count] operations into a single call. * - * @include [SelectingColumns.ColumnGroupsAndNestedColumnsMention] + * @include [SelectingColumns.ColumnGroupsAndNestedColumnsSnippet] * * See [Selecting Columns][SelectSelectingOptions]. * @@ -811,7 +812,7 @@ public fun GroupBy<*, G>.pivotCounts(inward: Boolean = true, columns: PivotC /** * @include [GroupByPivotCountsCommonDocs] - * @include [SelectingColumns.ColumnNames] + * @include [SelectingColumns.ColumnNamesApi] * * ### Example * ```kotlin @@ -913,7 +914,7 @@ public fun AggregateGroupedDsl.pivot( /** * @include [AggregateGroupedDslPivotDocs] - * @include [SelectingColumns.ColumnNames] + * @include [SelectingColumns.ColumnNamesApi] * ### Example * ```kotlin * df.groupBy("firstName").aggregate { @@ -1013,7 +1014,7 @@ public fun AggregateGroupedDsl.pivotMatches( /** * @include [AggregateGroupedDslPivotMatchesDocs] - * @include [SelectingColumns.ColumnNames] + * @include [SelectingColumns.ColumnNamesApi] * ### Example * ```kotlin * df.groupBy("firstName").aggregate { @@ -1099,7 +1100,7 @@ public fun AggregateGroupedDsl.pivotCounts( /** * @include [AggregateGroupedDslPivotCountsDocs] - * @include [SelectingColumns.ColumnNames] + * @include [SelectingColumns.ColumnNamesApi] * ### Example * ```kotlin * df.groupBy("firstName").aggregate { diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/remove.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/remove.kt index 0da7c1004a..bd0b6b73cd 100644 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/remove.kt +++ b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/remove.kt @@ -26,7 +26,7 @@ import kotlin.reflect.KProperty * * Removes the specified [columns] from the original [DataFrame] and returns a new [DataFrame] without them. * - * @include [SelectingColumns.ColumnGroupsAndNestedColumnsMention] + * @include [SelectingColumns.ColumnGroupsAndNestedColumnsSnippet] * * See [Selecting Columns][Select.SelectSelectingOptions]. * @@ -47,7 +47,7 @@ private typealias CommonRemoveDocs = Nothing /** * @include [CommonRemoveDocs] - * @include [SelectingColumns.Dsl.WithExample] {@include [SetRemoveOperationArg]} + * @include [SelectingColumns.ColumnsSelectionDsl.ColumnsSelectionDslWithExample] {@include [SetRemoveOperationArg]} * @param [columns] The [Columns Selector][ColumnsSelector] used to remove the columns of this [DataFrame]. */ @Refine @@ -57,14 +57,14 @@ public fun DataFrame.remove(columns: ColumnsSelector): DataFrame /** * @include [CommonRemoveDocs] - * @include [SelectingColumns.ColumnNames.WithExample] {@include [SetRemoveOperationArg]} + * @include [SelectingColumns.ColumnNamesApi.ColumnNamesApiWithExample] {@include [SetRemoveOperationArg]} * @param [columns] The [Column Names][String] used to remove the columns of this [DataFrame]. */ public fun DataFrame.remove(vararg columns: String): DataFrame = remove { columns.toColumnSet() } /** * @include [CommonRemoveDocs] - * @include [SelectingColumns.ColumnAccessors.WithExample] {@include [SetRemoveOperationArg]} + * * @param [columns] The [Column Accessors][ColumnReference] used to remove the columns of this [DataFrame]. */ @Deprecated(DEPRECATED_ACCESS_API) @@ -73,7 +73,7 @@ public fun DataFrame.remove(vararg columns: AnyColumnReference): DataFram /** * @include [CommonRemoveDocs] - * @include [SelectingColumns.KProperties.WithExample] {@include [SetRemoveOperationArg]} + * * @param [columns] The [KProperties][KProperty] used to remove the columns of this [DataFrame]. */ @Deprecated(DEPRECATED_ACCESS_API) diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/rename.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/rename.kt index 1be03a7b36..9912442ab8 100644 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/rename.kt +++ b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/rename.kt @@ -47,7 +47,7 @@ import kotlin.reflect.KProperty * * Check out [Grammar]. * - * @include [SelectingColumns.ColumnGroupsAndNestedColumnsMention] + * @include [SelectingColumns.ColumnGroupsAndNestedColumnsSnippet] * * See [Selecting Columns][RenameSelectingOptions]. * @@ -119,7 +119,7 @@ public fun DataFrame.rename(vararg mappings: Pair): DataF /** * @include [CommonRenameDocs] - * @include [SelectingColumns.Dsl] {@include [SetRenameOperationArg]} + * @include [SelectingColumns.ColumnsSelectionDsl] {@include [SetRenameOperationArg]} * ### Examples: * ```kotlin * // Rename "col1" to "width" and "col2" to "length" @@ -147,7 +147,7 @@ public fun DataFrame.rename(vararg cols: KProperty): RenameClause DataFrame.select(columns: ColumnsSelector): DataFrame /** * @include [CommonSelectDocs] - * @include [SelectingColumns.KProperties.WithExample] {@include [SetSelectOperationArg]} + * * @param [columns] The [KProperties][KProperty] used to select the columns of this [DataFrame]. */ @Deprecated(DEPRECATED_ACCESS_API) @@ -78,7 +78,7 @@ public fun DataFrame.select(vararg columns: KProperty<*>): DataFrame = /** * @include [CommonSelectDocs] - * @include [SelectingColumns.ColumnNames.WithExample] {@include [SetSelectOperationArg]} + * @include [SelectingColumns.ColumnNamesApi.ColumnNamesApiWithExample] {@include [SetSelectOperationArg]} * @param [columns] The [Column Names][String] used to select the columns of this [DataFrame]. */ @Refine @@ -87,7 +87,7 @@ public fun DataFrame.select(vararg columns: String): DataFrame = selec /** * @include [CommonSelectDocs] - * @include [SelectingColumns.ColumnAccessors.WithExample] {@include [SetSelectOperationArg]} + * * @param [columns] The [Column Accessors][ColumnReference] used to select the columns of this [DataFrame]. */ @Deprecated(DEPRECATED_ACCESS_API) diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/take.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/take.kt index eff681f9e5..b051fac67f 100644 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/take.kt +++ b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/take.kt @@ -7,7 +7,6 @@ import org.jetbrains.kotlinx.dataframe.DataRow import org.jetbrains.kotlinx.dataframe.RowFilter import org.jetbrains.kotlinx.dataframe.annotations.AccessApiOverload import org.jetbrains.kotlinx.dataframe.annotations.Interpretable -import org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl import org.jetbrains.kotlinx.dataframe.columns.ColumnPath import org.jetbrains.kotlinx.dataframe.columns.ColumnSet import org.jetbrains.kotlinx.dataframe.columns.ColumnWithPath @@ -18,7 +17,6 @@ import org.jetbrains.kotlinx.dataframe.documentation.CommonTakeAndDropWhileDocs import org.jetbrains.kotlinx.dataframe.documentation.TakeAndDropColumnsSelectionDslGrammar import org.jetbrains.kotlinx.dataframe.impl.columns.transform import org.jetbrains.kotlinx.dataframe.impl.columns.transformSingle -import org.jetbrains.kotlinx.dataframe.index import org.jetbrains.kotlinx.dataframe.nrow import org.jetbrains.kotlinx.dataframe.util.DEPRECATED_ACCESS_API import kotlin.reflect.KProperty diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/ungroup.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/ungroup.kt index 1cc5a25f08..ff3c8352b5 100644 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/ungroup.kt +++ b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/ungroup.kt @@ -49,7 +49,7 @@ private typealias CommonUngroupDocs = Nothing /** * @include [CommonUngroupDocs] - * @include [SelectingColumns.Dsl] {@include [SetUngroupOperationArg]} + * @include [SelectingColumns.ColumnsSelectionDsl] {@include [SetUngroupOperationArg]} * ### Examples: * ```kotlin * df.ungroup { groupA and groupB } @@ -65,7 +65,7 @@ public fun DataFrame.ungroup(columns: ColumnsSelector): DataFram /** * @include [CommonUngroupDocs] - * @include [SelectingColumns.ColumnNames.WithExample] {@include [SetUngroupOperationArg]} + * @include [SelectingColumns.ColumnNamesApi.ColumnNamesApiWithExample] {@include [SetUngroupOperationArg]} * @param [columns\] The [Column Names][String] used to select the columns of this [DataFrame] to ungroup. */ public fun DataFrame.ungroup(vararg columns: String): DataFrame = ungroup { columns.toColumnSet() } diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/update.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/update.kt index 7294059146..9211965097 100644 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/update.kt +++ b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/update.kt @@ -12,7 +12,6 @@ import org.jetbrains.kotlinx.dataframe.RowValueFilter import org.jetbrains.kotlinx.dataframe.annotations.AccessApiOverload import org.jetbrains.kotlinx.dataframe.annotations.Interpretable import org.jetbrains.kotlinx.dataframe.annotations.Refine -import org.jetbrains.kotlinx.dataframe.api.mean import org.jetbrains.kotlinx.dataframe.columns.ColumnGroup import org.jetbrains.kotlinx.dataframe.columns.ColumnReference import org.jetbrains.kotlinx.dataframe.columns.toColumnSet @@ -163,7 +162,7 @@ private typealias UpdateWithNote = Nothing /** * @include [CommonUpdateFunctionDoc] - * @include [SelectingColumns.Dsl.WithExample] {@include [SetSelectingColumnsOperationArg]} + * @include [SelectingColumns.ColumnsSelectionDsl.ColumnsSelectionDslWithExample] {@include [SetSelectingColumnsOperationArg]} * @include [Update.DslParam] */ @Interpretable("Update0") @@ -171,7 +170,7 @@ public fun DataFrame.update(columns: ColumnsSelector): Update DataFrame.update(vararg columns: String): Update = up /** * @include [CommonUpdateFunctionDoc] - * @include [SelectingColumns.KProperties.WithExample] {@include [SetSelectingColumnsOperationArg]} + * * @include [UpdateWithNote] * @include [Update.KPropertiesParam] */ @@ -189,7 +188,7 @@ public fun DataFrame.update(vararg columns: KProperty): Update Update.notNull(expression: UpdateExpression): * @include [CommonUpdateFunctionDoc] * This overload is a combination of [update] and [with][Update.with]. * - * @include [SelectingColumns.ColumnAccessors] - * * {@include [ExpressionsGivenRow.RowValueExpression.WithExample]} * {@set [ExpressionsGivenRow.OPERATION] [update][update]`("city")`} * @@ -475,8 +472,6 @@ public fun DataFrame.update( * @include [CommonUpdateFunctionDoc] * This overload is a combination of [update] and [with][Update.with]. * - * @include [SelectingColumns.KProperties] - * * {@include [ExpressionsGivenRow.RowValueExpression.WithExample]} * {@set [ExpressionsGivenRow.OPERATION] [update][update]`("city")`} * @@ -495,7 +490,7 @@ public fun DataFrame.update( * @include [CommonUpdateFunctionDoc] * This overload is a combination of [update] and [with][Update.with]. * - * @include [SelectingColumns.ColumnNames] + * @include [SelectingColumns.ColumnNamesApi] * * {@include [ExpressionsGivenRow.RowValueExpression.WithExample]} * {@set [ExpressionsGivenRow.OPERATION] [update][update]`("city")`} diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/valueCols.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/valueCols.kt index 287046df7d..e85eba6f8f 100644 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/valueCols.kt +++ b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/valueCols.kt @@ -12,7 +12,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.ValueColumn -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 @@ -70,7 +70,7 @@ public interface ValueColsColumnsSelectionDsl { * Creates a subset of columns from [this\] that are [ValueColumns][ValueColumn]. * * You can optionally use a [filter\] to only include certain columns. - * [valueCols] can be called using any of the supported [APIs][AccessApi] (+ [ColumnPath]). + * [valueCols] can be called using any of the supported [APIs][AccessApis] (+ [ColumnPath]). * * This function operates solely on columns at the top-level. * diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/AccessApi.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/AccessApi.kt deleted file mode 100644 index 8ae101c69d..0000000000 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/AccessApi.kt +++ /dev/null @@ -1,86 +0,0 @@ -package org.jetbrains.kotlinx.dataframe.documentation - -import org.jetbrains.kotlinx.dataframe.documentation.AccessApi.AnyApiLinks - -/** - * ## Access APIs - * - * By nature, dataframes are dynamic objects, column labels depend on the input source and also new columns could be added - * or deleted while wrangling. Kotlin, in contrast, is a statically typed language and all types are defined and verified - * ahead of execution. That's why creating a flexible, handy, and, at the same time, safe API to a dataframe is tricky. - * - * In `Kotlin DataFrame` we provide two different ways to access columns: - * @include [AnyApiLinks] - * - * For more information: {@include [DocumentationUrls.AccessApis]} - * - * @comment We can link to here whenever we want to explain the different access APIs. - */ -internal interface AccessApi { - - /** - * - {@include [ExtensionPropertiesApiLink]} - * - {@include [StringApiLink]} - */ - typealias AnyApiLinks = Nothing - - /** - * String API. - * In this [AccessApi], columns are accessed by a [String] representing their name. - * Type-checking is done at runtime, name-checking too. - * - * For more information: {@include [DocumentationUrls.AccessApis.StringApi]} - * - * For example: {@comment This works if you include the test module when running KoDEx} - * @sample [org.jetbrains.kotlinx.dataframe.samples.api.ApiLevels.strings] - */ - typealias StringApi = Nothing - - /** [String API][StringApi] */ - typealias StringApiLink = Nothing - - /** - * Column Accessors API. - * In this [AccessApi], every column has a descriptor; - * a variable that represents its name and type. - * - * For more information: {@include [DocumentationUrls.AccessApis.ColumnAccessorsApi]} - */ - typealias ColumnAccessorsApi = Nothing - - /** [Column Accessors API][AccessApi.ColumnAccessorsApi] */ - typealias ColumnAccessorsApiLink = Nothing - - /** - * KProperties API. - * In this [AccessApi], columns accessed by the - * [`KProperty`](https://kotlinlang.org/docs/reflection.html#property-references) - * of some class. - * The name and type of column should match the name and type of property, respectively. - * - * For more information: {@include [DocumentationUrls.AccessApis.KPropertiesApi]} - */ - typealias KPropertiesApi = Nothing - - /** [KProperties API][KPropertiesApi] */ - typealias KPropertiesApiLink = Nothing - - /** - * Extension Properties API. - * In this [AccessApi], extension access properties are generated based on the dataframe schema. - * The name and type of properties are inferred from the name and type of the corresponding columns. - * - * For more information: {@include [DocumentationUrls.AccessApis.ExtensionPropertiesApi]} - * - * For example, in notebooks extension properties are generated from runtime data after the cell is executed: {@comment This works if you include the test module when running KoDEx} - * @sample [org.jetbrains.kotlinx.dataframe.samples.api.ApiLevels.extensionProperties1] - * @sample [org.jetbrains.kotlinx.dataframe.samples.api.ApiLevels.extensionProperties2] - */ - typealias ExtensionPropertiesApi = Nothing - - /** [Extension Properties API][ExtensionPropertiesApi] */ - typealias ExtensionPropertiesApiLink = Nothing -} - -/** [Access API][AccessApi] */ -internal typealias AccessApiLink = Nothing diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/AccessApis.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/AccessApis.kt new file mode 100644 index 0000000000..4b6e3809a0 --- /dev/null +++ b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/AccessApis.kt @@ -0,0 +1,101 @@ +package org.jetbrains.kotlinx.dataframe.documentation + +import org.jetbrains.kotlinx.dataframe.DataFrame + +/* + * Access APIs KDoc-topic. + * Link to here whenever you want to explain the different access APIs + * with `@include [AccessApiLink]`. + */ + +/** + * ## Access APIs + * + * Accessing and specifying columns is the one of the most important parts of the API, + * used in the most of [DataFrame] operations. + * + * In the Kotlin DataFrame library, we provide two different ways to access columns — + * the {@include [StringApiLink]} and the {@include [ExtensionPropertiesApiLink]}. + * + * For more information: {@include [DocumentationUrls.AccessApis]} + */ +internal interface AccessApis { + + /* + * String API KDoc-topic. + * Link to it with `@include [StringApiLink]`. + */ + + /** + * ## String API + * + * In this [AccessApis], columns are accessed by a [String] representing their name. + * Type-checking and name-checking are done at runtime, too. + * + * ### String Column Accessors + * + * You can also specify a column using a [String] representing their name + * and path inside the [Columns Selection DSL][SelectingColumns.ColumnsSelectionDsl] and + * [Row Expressions][ExpressionsGivenRow]. + * + * For more information: {@include [DocumentationUrls.AccessApis.StringApi]} + */ + typealias StringAPI = Nothing + + /** [String API][`StringAPI`] */ + typealias StringApiLink = Nothing + + /* + * Extension Properties API KDoc topic. + * Link to it with `@include [ExtensionPropertiesApiLink]`. + */ + + /** + * ## Extension Properties API + * + * When working with a [DataFrame], the most convenient and reliable way to [access its columns][AccessApis] — + * including for operations and retrieving column values in row expressions — + * is through auto-generated extension properties. + * + * These properties are generated based on the + * [dataframe schema][org.jetbrains.kotlinx.dataframe.schema.DataFrameSchema], + * with their names and types inferred from the names and types of the corresponding columns. + * This also works for hierarchical [DataFrame] structures + * (i.e., [column groups][org.jetbrains.kotlinx.dataframe.columns.ColumnGroup] + * and [frame columns][org.jetbrains.kotlinx.dataframe.columns.FrameColumn]). + * + * ### Example + * + * Given the following [DataFrame]: + * + * | name | age | height | + * |-------|-----|--------| + * | Alice | 23 | 175.5 | + * | Bob | 27 | 160.2 | + * + * You can access columns using extension properties in a type-safe way, avoiding typos and relying on autocompletion. + * These properties can be used in: + * - [Columns Selection DSL][SelectingColumns.ColumnsSelectionDsl] + * - [Row Expressions][ExpressionsGivenRow] + * + * ```kotlin + * // Access the "name" column + * df.name + * + * // Select the "age" and "height" columns + * df.select { age and height } + * + * // Filter rows where "age" > 18 and "name" starts with 'A' + * df.filter { age > 18 && name.startsWith("A") } + * ``` + * + * For more information: {@include [DocumentationUrls.AccessApis.ExtensionPropertiesApi]} + */ + typealias ExtensionPropertiesApi = Nothing + + /** [Extension Properties API][ExtensionPropertiesApi] */ + typealias ExtensionPropertiesApiLink = Nothing +} + +/** [Access APIs][AccessApis] */ +internal typealias AccessApiLink = Nothing diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/AutoRenaming.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/AutoRenaming.kt deleted file mode 100644 index 0669095988..0000000000 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/AutoRenaming.kt +++ /dev/null @@ -1,19 +0,0 @@ -package org.jetbrains.kotlinx.dataframe.documentation - -import org.jetbrains.kotlinx.dataframe.DataFrame - -/** - * ## Auto-renaming in [DataFrame] - * - * In some operations, multiple columns with the same name may appear - * in the resulting [DataFrame]. - * - * In such cases, columns with duplicate names are automatically renamed - * using the pattern `"\$name\$n"`, where `name` is the original column name - * and `n` is a unique index (1, 2, 3, and so on); - * the first time the name of the column is encountered, no number is appended. - * - * It is recommended to [rename][org.jetbrains.kotlinx.dataframe.api.rename] them - * to maintain clarity and improve code readability. - */ -internal typealias AutoRenaming = Nothing diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/ColumnExpression.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/ColumnExpression.kt index cbe7f2338f..0f81c7bd53 100644 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/ColumnExpression.kt +++ b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/ColumnExpression.kt @@ -1,26 +1,23 @@ package org.jetbrains.kotlinx.dataframe.documentation -import org.jetbrains.kotlinx.dataframe.api.AddDsl -import org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl -import org.jetbrains.kotlinx.dataframe.api.CreateDataFrameDsl import org.jetbrains.kotlinx.dataframe.api.expr +/* + * Column Expression KDoc-topic. + * Link to it with `@include [ColumnExpressionLink]`. + */ + /** * ## Column Expression - * In many DSLs, the lambda `expr {}` can be used to + * In many DSLs, the lambda [`expr {}`][expr] can be used to * create a new column by defining an expression to fill up each row. * - * These DSLs include (but are not limited to): - * [The Add DSL][AddDsl.expr], [The Columns Selection DSL][ColumnsSelectionDsl.expr], and - * [The Create DataFrame DSL][CreateDataFrameDsl.expr]. - * - * `expr {}` behaves like a mapping statement, iterating over the object it's called on. + * [`expr {}`][expr] behaves like a mapping statement, iterating over the object it's called on. */ internal interface ColumnExpression { /** - * ## Column Expression - * Create a temporary new column by defining an expression to fill up each row. + * Creates a temporary new column by defining an expression to fill up each row. * * See {@include [ColumnExpressionLink]} for more information. */ diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/ColumnPathCreation.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/ColumnPathCreation.kt deleted file mode 100644 index 6f7f56e8ae..0000000000 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/ColumnPathCreation.kt +++ /dev/null @@ -1,9 +0,0 @@ -@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. - */ -internal typealias ColumnPathCreation = Nothing diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/CommonTakeAndDropWhileDocs.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/CommonTakeAndDropWhileDocs.kt index e7a66602ba..bc8bc60c3e 100644 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/CommonTakeAndDropWhileDocs.kt +++ b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/CommonTakeAndDropWhileDocs.kt @@ -42,7 +42,6 @@ import org.jetbrains.kotlinx.dataframe.columns.ColumnWithPath * @param [predicate\] The [ColumnFilter] to control which columns to {@get [NOUN]}. * @return A [ColumnSet] containing the {@get [FIRST_OR_LAST]} columns adhering to the [predicate\]. */ -@Suppress("ClassName") internal interface CommonTakeAndDropWhileDocs { /** Title, like "Take Last" */ diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/DocumentationUrls.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/DocumentationUrls.kt index 829e26e931..3e8c66634c 100644 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/DocumentationUrls.kt +++ b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/DocumentationUrls.kt @@ -2,6 +2,14 @@ package org.jetbrains.kotlinx.dataframe.documentation +/* + * Documentation URLs KDoc-snippets. + * + * Contains all links to Kotlin DataFrame documentation pages. + * + * Include it in KDoc with `@include [-class-]`. + * For example: `For more information: {@include [DocumentationUrls.SomeUrl]}`. + */ internal interface DocumentationUrls { /** https://kotlin.github.io/dataframe */ @@ -13,12 +21,6 @@ internal interface DocumentationUrls { /** [See String API on the documentation website.]({@include [Url]}/stringapi.html) */ typealias StringApi = Nothing - /** [See Column Accessors API on the documentation website.]({@include [Url]}/columnaccessorsapi.html) */ - typealias ColumnAccessorsApi = Nothing - - /** [See KProperties API on the documentation website.]({@include [Url]}/kpropertiesapi.html) */ - typealias KPropertiesApi = Nothing - /** [See Extension Properties API on the documentation website.]({@include [Url]}/extensionpropertiesapi.html) */ typealias ExtensionPropertiesApi = Nothing } @@ -26,9 +28,6 @@ internal interface DocumentationUrls { /** [See Column Selectors on the documentation website.]({@include [Url]}/columnselectors.html) */ typealias ColumnSelectors = Nothing - /** [See Extension Properties API on the documentation website.]({@include [Url]}/extensionpropertiesapi.html) */ - typealias ExtensionPropertiesApi = Nothing - /** [See Compiler Plugin on the documentation website.]({@include [Url]}/compiler-plugin.html) */ typealias CompilerPlugin = Nothing diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/DslGrammar.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/DslGrammar.kt index 6066451683..db8af0f505 100644 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/DslGrammar.kt +++ b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/DslGrammar.kt @@ -1,5 +1,10 @@ package org.jetbrains.kotlinx.dataframe.documentation +/* + * DSL Grammar KDoc-topic. + * Link to it with `@include [DslGrammarLink]`. + */ + /** * ## DSL Grammar * diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/DslGrammarTemplateColumnsSelectionDsl.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/DslGrammarTemplateColumnsSelectionDsl.kt index 136ed24eb7..f75908ee4d 100644 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/DslGrammarTemplateColumnsSelectionDsl.kt +++ b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/DslGrammarTemplateColumnsSelectionDsl.kt @@ -57,7 +57,6 @@ public interface DslGrammarTemplateColumnsSelectionDsl { * {@get [DslGrammarTemplate.COLUMN_GROUP_FUNCTIONS]} * } */ - @Suppress("ClassName") public interface DslGrammarTemplate { // region parts diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/ExtensionPropertiesAPI.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/ExtensionPropertiesAPI.kt deleted file mode 100644 index dfd2df9ee6..0000000000 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/ExtensionPropertiesAPI.kt +++ /dev/null @@ -1,43 +0,0 @@ -package org.jetbrains.kotlinx.dataframe.documentation - -import org.jetbrains.kotlinx.dataframe.DataFrame - -/** - * ## Extension Properties API - * - * When working with a [DataFrame], the most convenient and reliable way to access its columns — - * including for operations and retrieving column values in row expressions — is through auto-generated extension properties. - * - * These properties are generated based on the - * [DataFrame schema][org.jetbrains.kotlinx.dataframe.schema.DataFrameSchema], - * with their names and types inferred from the names and types of the corresponding columns. - * This also works for hierarchical [DataFrame] structures (i.e., column groups). - * - * ### Example - * - * Given the following [DataFrame]: - * - * | name | age | height | - * |-------|-----|--------| - * | Alice | 23 | 175.5 | - * | Bob | 27 | 160.2 | - * - * You can access columns using extension properties in a type-safe way, avoiding typos and relying on autocompletion. - * These properties can be used in: - * - [Columns Selection DSL][SelectingColumns.Dsl.WithExample] - * - [DataRow Expressions][ExpressionsGivenRow] - * - * ```kotlin - * // Access the "name" column - * df.name - * - * // Select the "age" and "height" columns - * df.select { age and height } - * - * // Filter rows where "age" > 18 and "name" starts with 'A' - * df.filter { age > 18 && name.startsWith("A") } - * ``` - * - * For more information, see: {@include [DocumentationUrls.ExtensionPropertiesApi]} - */ -internal typealias ExtensionPropertiesAPIDocs = Nothing diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/Issues.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/Issues.kt index 44cc89317d..fc7bd6cc6c 100644 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/Issues.kt +++ b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/Issues.kt @@ -2,6 +2,16 @@ package org.jetbrains.kotlinx.dataframe.documentation +/* + * Issues URLs KDoc-snippets. + * + * Contains all links to Kotlin DataFrame related issues. + * Note that Kotlin/dataframe issues can be simply written as `#1234`. + * + * Include it in KDoc with `@include [-class-]`. + * For example: `@include [Issues.ConflictingOverloadsK2Link]`. + */ + internal interface Issues { /** [#KT-68546](https://youtrack.jetbrains.com/issue/KT-68546/Conflicting-overloads-in-non-generic-interface-K2-2.0.0) */ diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/NA.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/NA.kt index 1a5c786f07..214901c86c 100644 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/NA.kt +++ b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/NA.kt @@ -5,6 +5,11 @@ import org.jetbrains.kotlinx.dataframe.DataRow import org.jetbrains.kotlinx.dataframe.api.dropNA import org.jetbrains.kotlinx.dataframe.api.fillNA +/* + * NA KDoc-topic. + * Link to it with `@include [NALink]`. + */ + /** * ## `NA` * `NA` in Dataframe can be seen as "[NaN] or `null`". @@ -21,6 +26,9 @@ import org.jetbrains.kotlinx.dataframe.api.fillNA * * For more information: {@include [DocumentationUrls.NanAndNa.NA]} * - * @see NaN + * @see [NaN] */ internal typealias NA = Nothing + +/** [`NA`][NA] */ +internal typealias NALink = Nothing diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/NaN.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/NaN.kt index 71c9ab5d1f..8d1bfdd0bb 100644 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/NaN.kt +++ b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/NaN.kt @@ -3,8 +3,14 @@ package org.jetbrains.kotlinx.dataframe.documentation import org.jetbrains.kotlinx.dataframe.api.dropNaNs import org.jetbrains.kotlinx.dataframe.api.fillNaNs +/* + * NaN KDoc-topic. + * Link to it with `@include [NaNLink]`. + */ + /** * ## `NaN` + * * [Floats][Float] or [Doubles][Double] can be represented as [Float.NaN] or [Double.NaN], respectively, * in cases where a mathematical operation is undefined, such as dividing by zero. * @@ -13,6 +19,9 @@ import org.jetbrains.kotlinx.dataframe.api.fillNaNs * * For more information: {@include [DocumentationUrls.NanAndNa.NaN]} * - * @see NA + * @see [NA] */ internal typealias NaN = Nothing + +/** [`NaN`][NaN] */ +internal typealias NaNLink = Nothing diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/RowFilterDescription.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/RowFilterDescription.kt deleted file mode 100644 index 617364b480..0000000000 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/RowFilterDescription.kt +++ /dev/null @@ -1,13 +0,0 @@ -package org.jetbrains.kotlinx.dataframe.documentation - -import org.jetbrains.kotlinx.dataframe.DataRow -import org.jetbrains.kotlinx.dataframe.RowFilter - -/** - * The [predicate] is a [RowFilter] — a lambda that receives each [DataRow] as both `this` and `it` - * and is expected to return a [Boolean] value. - * - * It allows you to define conditions using the row's values directly, - * including through [extension properties][ExtensionPropertiesAPIDocs] for convenient and type-safe access. - */ -internal typealias RowFilterDescription = Nothing diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/SelectingColumns.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/SelectingColumns.kt index 6c4e80d77a..dc0c813c7f 100644 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/SelectingColumns.kt +++ b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/SelectingColumns.kt @@ -6,45 +6,43 @@ import org.jetbrains.kotlinx.dataframe.DataFrame import org.jetbrains.kotlinx.dataframe.api.ColumnSelectionDslLink import org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl import org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDslLink -import org.jetbrains.kotlinx.dataframe.api.colsOf -import org.jetbrains.kotlinx.dataframe.api.column -import org.jetbrains.kotlinx.dataframe.api.fillNulls -import org.jetbrains.kotlinx.dataframe.api.gather -import org.jetbrains.kotlinx.dataframe.api.select -import org.jetbrains.kotlinx.dataframe.api.update import org.jetbrains.kotlinx.dataframe.columns.ColumnGroup -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 kotlin.reflect.KProperty /** [Selecting Columns][SelectingColumns] */ @ExcludeFromSources internal typealias SelectingColumnsLink = Nothing +/* + * Selecting Columns KDoc-topic. + * Link to it with `@include [SelectingColumnsLink]`. + */ + /** * ## Selecting Columns - * Selecting columns for various operations (including but not limited to - * [DataFrame.select], [DataFrame.update], [DataFrame.gather], and [DataFrame.fillNulls]) + * + * Selecting columns for various [DataFrame] operations * can be done in the following ways: - * ### 1. {@include [DslLink]} - * {@include [Dsl.WithExample]} - * #### NOTE: There's also a 'single column' variant used sometimes: {@include [DslSingleLink]}. - * ### 2. {@include [ColumnNamesLink]} - * {@include [ColumnNames.WithExample]} - * ### 3. {@include [ColumnAccessorsLink]} - * {@include [ColumnAccessors.WithExample]} - * ### 4. {@include [KPropertiesLink]} - * {@include [KProperties.WithExample]} + * ### 1. {@include [CSDslWithExampleLink]} + * {@include [ColumnsSelectionDsl.ColumnsSelectionDslWithExample]} + * > There's also a 'single column' variant used sometimes: {@include [CSDslSingleWithExampleLink]}. + * ### 2. {@include [ColumnNamesWithExampleLink]} + * {@include [ColumnNamesApi.ColumnNamesApiWithExample]} */ internal interface SelectingColumns { + /* + * Note about column groups and nested columns KDoc-snippet. + * Paste it into KDoc using `@include [ColumnGroupsAndNestedColumnsSnippet]`. + */ + /** * This can include [column groups][ColumnGroup] and nested columns. */ @ExcludeFromSources - typealias ColumnGroupsAndNestedColumnsMention = Nothing + typealias ColumnGroupsAndNestedColumnsSnippet = Nothing /* * The key for a @set that will define the operation name for the examples below. @@ -68,32 +66,35 @@ internal interface SelectingColumns { @ExcludeFromSources typealias SetDefaultReceiverArg = Nothing + /* + * Columns Selection DSL KDoc-topic. + * Link to it with `@include [CSDslLink]` + * or paste it into KDoc with `@include [`Columns Selection DSL`]`. + */ + /** * Select or express columns using the {@include [ColumnsSelectionDslLink]}. - * (Any (combination of) {@include [AccessApiLink]}). * * This DSL is initiated by a [Columns Selector][ColumnsSelector] lambda, * which operates in the context of the {@include [ColumnsSelectionDslLink]} and * expects you to return a [SingleColumn] or [ColumnSet] (so, a [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. - * This also allows you to use [Extension Properties API][ExtensionPropertiesAPIDocs] - * for type- and name-safe columns selection. - * - * #### NOTE: - * While you can use the {@include [AccessApi.StringApiLink]} and {@include [AccessApi.KPropertiesApiLink]} - * in this DSL directly with any function, they are NOT valid return types for the - * [Columns Selector][ColumnsSelector] lambda. You'd need to turn them into a [ColumnReference] first, for instance - * with a function like [`col("name")`][ColumnsSelectionDsl.col]. * - * ### Check out: [Columns Selection DSL Grammar][ColumnsSelectionDsl.DslGrammar] + * Check out: [Columns Selection DSL Grammar][ColumnsSelectionDsl.DslGrammar] * {@include [LineBreak]} * @include [DocumentationUrls.ColumnSelectors] */ - interface Dsl { + interface ColumnsSelectionDsl { + + /* + * Columns Selection DSL with example KDoc-topic. + * Link to it with `@include [CSDslWithExampleLink]` + * or paste it into KDoc with `@include [`Columns Selection DSL with Example`]` + */ /** - * {@include [Dsl]} + * {@include [ColumnsSelectionDsl]} * * #### For example: * @@ -106,12 +107,22 @@ internal interface SelectingColumns { * @include [SetDefaultOperationArg] * @include [SetDefaultReceiverArg] */ - typealias WithExample = Nothing + typealias ColumnsSelectionDslWithExample = Nothing } - /** [Columns Selection DSL][Dsl.WithExample] */ + /** [Columns Selection DSL][ColumnsSelectionDsl] */ + @ExcludeFromSources + typealias CSDslLink = Nothing + + /** [Columns Selection DSL][ColumnsSelectionDsl.ColumnsSelectionDslWithExample] */ @ExcludeFromSources - typealias DslLink = Nothing + typealias CSDslWithExampleLink = Nothing + + /* + * Column Selection DSL KDoc-topic. + * Link to it with `@include [CSDslSingleLink]` + * or paste it into KDoc with `@include [`Column Selection DSL`]`. + */ /** * Select or express a single column using the Column Selection DSL. @@ -123,100 +134,79 @@ internal interface SelectingColumns { * This is an entity formed by calling any (combination) of the functions * in the DSL that is or can be resolved into a single column. * - * #### NOTE: - * While you can use the {@include [AccessApi.StringApiLink]} and {@include [AccessApi.KPropertiesApiLink]} - * in this DSL directly with any function, they are NOT valid return types for the - * [Column Selector][ColumnSelector]/[Columns Selector][ColumnsSelector] lambda. You'd need to turn them into a [ColumnReference] first, for instance - * with a function like [`col("name")`][ColumnsSelectionDsl.col]. * * {@include [LineBreak]} * @include [DocumentationUrls.ColumnSelectors] */ - interface DslSingle { + interface ColumnSelectionDsl { + + /* + * Column Selection DSL with example KDoc-topic. + * Link to it with `@include [CSDslSingleWithExampleLink]` + * or paste it into KDoc with `@include [`Column Selection DSL with Example`]` + */ /** - * {@include [DslSingle]} + * {@include [ColumnSelectionDsl]} * * #### For example: * - * `df.`{@get [OPERATION]}` { length }` + * {@get [RECEIVER]}`.`{@get [OPERATION]}` { length }` + * + * {@get [RECEIVER]}`.`{@get [OPERATION]}` { `[col][ColumnsSelectionDsl.col]`(1) }` * - * `df.`{@get [OPERATION]}` { `[col][ColumnsSelectionDsl.col]`(1) }` + * {@get [RECEIVER]}`.`{@get [OPERATION]}` { `[colsOf][ColumnsSelectionDsl.colsOf]`<`[Double][Double]`>().`[first][ColumnsSelectionDsl.first]`() }` * - * `df.`{@get [OPERATION]}` { `[colsOf][ColumnsSelectionDsl.colsOf]`<`[Double][Double]`>().`[first][ColumnsSelectionDsl.first]`() }` * @include [SetDefaultOperationArg] + * @include [SetDefaultReceiverArg] */ - typealias WithExample = Nothing + typealias ColumnsSelectionDslWithExample = Nothing } - /** [Column Selection DSL][DslSingle.WithExample] */ + /** [Column Selection DSL][ColumnSelectionDsl] */ @ExcludeFromSources - typealias DslSingleLink = Nothing - - /** - * Select columns using their [column names][String] - * ({@include [AccessApi.StringApiLink]}). - */ - interface ColumnNames { + typealias CSDslSingleLink = Nothing - /** - * {@include [ColumnNames]} - * - * #### For example: - * - * `df.`{@get [OPERATION]}`("length", "age")` - * @include [SetDefaultOperationArg] - */ - typealias WithExample = Nothing - } - - /** [Column names][ColumnNames.WithExample] */ + /** [Column Selection DSL][ColumnSelectionDsl.ColumnsSelectionDslWithExample] */ @ExcludeFromSources - typealias ColumnNamesLink = Nothing + typealias CSDslSingleWithExampleLink = Nothing + + /* + * Column Names API KDoc-topic. + * Link to it with `@include [ColumnNamesLink]` + * or paste it into KDoc with `@include [`Column Names API`]`. + */ /** - * Select columns using [column accessors][ColumnReference] - * ({@include [AccessApi.ColumnAccessorsApiLink]}). + * Select single or multiple columns using their names as [String]s. + * ({@include [AccessApis.StringApiLink]}). */ - interface ColumnAccessors { + interface ColumnNamesApi { + + /* + * CColumn Names API with Example KDoc-topic. + * Link to it with `@include [ColumnNamesWithExampleLink]` + * or paste it into KDoc with `@include [`Column Names API with Example`]`. + */ /** - * {@include [ColumnAccessors]} + * {@include [ColumnNamesApi]} * * #### For example: * - * `val length by `[column][column]`<`[Double][Double]`>()` + * {@get [RECEIVER]}`.`{@get [OPERATION]}`("length", "age")` * - * `val age by `[column][column]`<`[Double][Double]`>()` - * - * `df.`{@get [OPERATION]}`(length, age)` * @include [SetDefaultOperationArg] + * @include [SetDefaultReceiverArg] */ - typealias WithExample = Nothing + typealias ColumnNamesApiWithExample = Nothing } - /** [Column references][ColumnAccessors.WithExample] */ + /** [Column names][ColumnNamesApi] */ @ExcludeFromSources - typealias ColumnAccessorsLink = Nothing - - /** Select columns using [KProperties][KProperty] ({@include [AccessApi.KPropertiesApiLink]}). */ - interface KProperties { - - /** - * {@include [KProperties]} - * - * #### For example: - * ```kotlin - * data class Person(val length: Double, val age: Double) - * ``` - * - * `df.`{@get [OPERATION]}`(Person::length, Person::age)` - * @include [SetDefaultOperationArg] - */ - typealias WithExample = Nothing - } + typealias ColumnNamesLink = Nothing - /** [KProperties][KProperties.WithExample] */ + /** [Column names][ColumnNamesApi.ColumnNamesApiWithExample] */ @ExcludeFromSources - typealias KPropertiesLink = Nothing + typealias ColumnNamesWithExampleLink = Nothing } diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/SelectingRows.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/SelectingRows.kt index 078bea504f..0528503c2f 100644 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/SelectingRows.kt +++ b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/SelectingRows.kt @@ -1,10 +1,8 @@ -@file:Suppress("ClassName") - package org.jetbrains.kotlinx.dataframe.documentation +import org.jetbrains.kotlinx.dataframe.DataRow import org.jetbrains.kotlinx.dataframe.RowFilter import org.jetbrains.kotlinx.dataframe.RowValueFilter -import org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl import org.jetbrains.kotlinx.dataframe.api.count import org.jetbrains.kotlinx.dataframe.api.diff import org.jetbrains.kotlinx.dataframe.api.drop @@ -17,6 +15,7 @@ import org.jetbrains.kotlinx.dataframe.index /** * ## Selecting Rows + * * Selecting rows that satisfy a "Row Condition" ({@include [DocumentationUrls.DataRow.RowConditions]}) * can occur in the following two types of operations: * - Selecting entire rows ({@include [RowConditionLink]}), for instance in [filter], [drop], [first], and [count] @@ -29,6 +28,43 @@ import org.jetbrains.kotlinx.dataframe.index */ internal interface SelectingRows { + /* + * Row filter KDoc-snippet. + * Include it into KDoc with `@include [`Selecting Rows`.RowFilterSnippet]`. + */ + + /** + * The [predicate] is a [RowFilter] — a lambda that receives each [DataRow] as both `this` and `it` + * and is expected to return a [Boolean] value. + * + * It allows you to define conditions using the row's values directly, + * including through [extension properties][AccessApis.ExtensionPropertiesApi] + * for convenient and type-safe access. + * + * Fore more information, {@include [DocumentationUrls.DataRow.RowConditions]} + */ + @ExcludeFromSources + typealias RowFilterSnippet = Nothing + + /* + * Row filter KDoc-snippet. + * Include it into KDoc with `@include [`Selecting Rows`.RowValueFilterSnippet]`. + */ + + /** + * The [predicate] is a [RowValueFilter] — a lambda that receives each [DataRow] as `this` and + * given value as `it` + * and is expected to return a [Boolean] value. + * + * It allows you to define conditions using the row's values directly, + * including through [extension properties][AccessApis.ExtensionPropertiesApi] + * for convenient and type-safe access. + * + * Fore more information, {@include [DocumentationUrls.DataRow.RowConditions]} + */ + @ExcludeFromSources + typealias RowValueFilterSnippet = Nothing + /* * The key for a @set that will define the operation name for the examples below. * Make sure to [alias][your examples]. diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/snippets.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/snippets.kt new file mode 100644 index 0000000000..f3d5307c40 --- /dev/null +++ b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/snippets.kt @@ -0,0 +1,42 @@ +package org.jetbrains.kotlinx.dataframe.documentation + +import org.jetbrains.kotlinx.dataframe.DataFrame + +// File with KDF common KDoc-topics and -snippets. + +/* + * Auto-renaming in [DataFrame] KDoc-topic. + * Link to it with `@include [AutoRenamingLink]`. + */ + +/** + * ## Auto-renaming in [DataFrame] + * + * In some operations, multiple columns with the same name may appear + * in the resulting [DataFrame]. + * + * In such cases, columns with duplicate names are automatically renamed + * using the pattern `"\$name\$n"`, where `name` is the original column name + * and `n` is a unique index (1, 2, 3, and so on); + * the first time the name of the column is encountered, no number is appended. + * + * It is recommended to [rename][org.jetbrains.kotlinx.dataframe.api.rename] them + * to maintain clarity and improve code readability. + */ +internal typealias AutoRenamingColumnsInDataFrame = Nothing + +/** [Auto-renaming columns in DataFrame][AutoRenamingColumnsInDataFrame] */ +@ExcludeFromSources +internal typealias AutoRenamingLink = Nothing + +/* + * Column Path auto creation KDoc-snippet. + * Include it in KDoc with `@include [ColumnPathCreationSnippet]`. + */ + +/** + * 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 typealias ColumnPathCreationSnippet = Nothing diff --git a/dataframe-json/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/json.kt b/dataframe-json/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/json.kt index 5a825b69b9..4949d1f104 100644 --- a/dataframe-json/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/json.kt +++ b/dataframe-json/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/json.kt @@ -24,7 +24,6 @@ import org.jetbrains.kotlinx.dataframe.impl.io.encodeFrame import org.jetbrains.kotlinx.dataframe.impl.io.encodeRow import org.jetbrains.kotlinx.dataframe.impl.io.readJsonImpl import org.jetbrains.kotlinx.dataframe.io.JSON.TypeClashTactic -import org.jetbrains.kotlinx.dataframe.io.JSON.TypeClashTactic.ANY_COLUMNS import org.jetbrains.kotlinx.dataframe.io.JSON.TypeClashTactic.ARRAY_AND_VALUE_COLUMNS import java.io.File import java.io.InputStream