Skip to content

KDocs fixes for distinct and distinctBy #1628

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Allex-Nik wants to merge 1 commit into
base: master
Choose a base branch
from
Open

KDocs fixes for distinct and distinctBy #1628

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 39 additions & 10 deletions core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/distinct.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,11 @@ package org.jetbrains.kotlinx.dataframe.api
import org.jetbrains.kotlinx.dataframe.AnyColumnReference
import org.jetbrains.kotlinx.dataframe.ColumnsSelector
import org.jetbrains.kotlinx.dataframe.DataFrame
import org.jetbrains.kotlinx.dataframe.DataRow
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.DistinctDocs.DISTINCT_RETURN
import org.jetbrains.kotlinx.dataframe.api.Select.SelectSelectingOptions
import org.jetbrains.kotlinx.dataframe.columns.ColumnSet
import org.jetbrains.kotlinx.dataframe.columns.SingleColumn
Expand All @@ -23,24 +25,27 @@ import kotlin.reflect.KProperty
// region DataFrame

/**
* ## The Distinct Operation
* ## The {@get NAME Distinct} Operation
*
* It removes duplicated rows based on {@get PHRASE_ENDING}.
* {@get DESCRIPTION It removes duplicated rows based on {@get PHRASE_ENDING}}.
Copy link
Collaborator

@AndreiKingsley AndreiKingsley Dec 9, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please, change in all kdocs "It removes .." -> "Removes .."

Copy link
Collaborator

@Jolanrensen Jolanrensen Dec 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please make sure all @get/@set keys are [references]. This will work too, but references are refactor- and typo-safe :)

Copy link
Collaborator

@Jolanrensen Jolanrensen Dec 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See https://github.com/Kotlin/dataframe/blob/master/KDOC_PREPROCESSING.md#arg-interfaces

Copy link
Collaborator Author

@Allex-Nik Allex-Nik Dec 12, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Then I need to include DESCRIPTION and PHRASE_ENDING into DistinctDocs like this, right?

private interface DistinctDocs {
    interface DISTINCT_PARAM

    interface DISTINCT_RETURN

    interface DESCRIPTION

    interface PHRASE_ENDING
}

*
* __NOTE:__ The rows in the resulting [DataFrame] are in the same order as they were in the original [DataFrame].
* __NOTE:__ The [rows][DataRow] in the resulting [DataFrame] are in the same order
* as they were in the original [DataFrame].
*
* {@get [DISTINCT_PARAM] @param [columns]
* The names of the columns to consider for evaluating distinct rows.}
* {@get [DISTINCT_PARAM]}
*
* @return A new DataFrame containing only distinct rows.
* {@get [DISTINCT_RETURN] @return A new [DataFrame] containing only distinct rows.}
*
* @see [Selecting Columns][SelectSelectingOptions].
Copy link
Collaborator

@AndreiKingsley AndreiKingsley Dec 9, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's rewrite this section with our template:

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

Line 109 in 5d6b7af

* @include [SelectingColumns.ColumnGroupsAndNestedColumnsMention]

Something like that

See also [distinctBy], that (write difference here)

 @include [SelectingColumns.ColumnGroupsAndNestedColumnsMention]
 
 See [Selecting Columns][ConvertSelectingOptions].
 
 For more information: {@include [DocumentationUrls.Distinct]}

* @see {@include [DocumentationUrls.Distinct]}
Copy link
Collaborator

@Jolanrensen Jolanrensen Dec 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

never used @see like that :o seems to work well!

* @see {@include [DocumentationUrls.DistinctBy]}
*/
@ExcludeFromSources
@Suppress("ClassName")
private interface DistinctDocs {
interface DISTINCT_PARAM

interface DISTINCT_RETURN
}

/**
Expand All @@ -52,15 +57,21 @@ public fun <T> DataFrame<T>.distinct(): DataFrame<T> = distinctBy { all() }

/**
* {@include [DistinctDocs]}
* {@set PHRASE_ENDING the specified columns}.
* {@set DESCRIPTION It selects the specified columns and keeps only distinct rows based on these selected columns}
* {@set [DistinctDocs.DISTINCT_PARAM] @param [columns] The names of the columns to select
Copy link
Collaborator

@Jolanrensen Jolanrensen Dec 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it's not "The names of the columns" though, it's a columns selector. Check how we write the @param of columnsSelectors in other operations :)

Copy link
Collaborator

@Jolanrensen Jolanrensen Dec 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's probably best to just write the @param line at the bottom of this KDoc, as each overload needs a different line of text for it. Yes, it will be below the @return then, but the IDE still renders it well.

* and to consider for evaluating distinct rows.}
* {@set [DISTINCT_RETURN] @return A new [DataFrame] containing only selected columns and distinct rows.}
*/
@Refine
@Interpretable("Distinct0")
public fun <T, C> DataFrame<T>.distinct(columns: ColumnsSelector<T, C>): DataFrame<T> = select(columns).distinct()

/**
* {@include [DistinctDocs]}
* {@set PHRASE_ENDING the specified columns}.
* {@set DESCRIPTION It selects the specified columns and keeps only distinct rows based on these selected columns}
* {@set [DistinctDocs.DISTINCT_PARAM] @param [columns] The names of the columns to select
Copy link
Collaborator Author

@Allex-Nik Allex-Nik Dec 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I changed the description of the parameter for some functions to mention that it is also used to select columns.

Copy link
Collaborator

@Jolanrensen Jolanrensen Dec 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it's also not "the names" here

Copy link
Collaborator

@Jolanrensen Jolanrensen Dec 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

but as this function is deprecated, you can probably remove the kdocs altogether

* and to consider for evaluating distinct rows.}
* {@set [DISTINCT_RETURN] @return A new [DataFrame] containing only selected columns and distinct rows.}
*/
@Deprecated(DEPRECATED_ACCESS_API)
@AccessApiOverload
Expand All @@ -72,13 +83,19 @@ public fun <T> DataFrame<T>.distinct(vararg columns: KProperty<*>): DataFrame<T>

/**
* {@include [DistinctDocs]}
* {@set PHRASE_ENDING the specified columns}.
* {@set DESCRIPTION It selects the specified columns and keeps only distinct rows based on these selected columns}
* {@set [DistinctDocs.DISTINCT_PARAM] @param [columns] The names of the columns to select
* and to consider for evaluating distinct rows.}
* {@set [DISTINCT_RETURN] @return A new [DataFrame] containing only selected columns and distinct rows.}
*/
public fun <T> DataFrame<T>.distinct(vararg columns: String): DataFrame<T> = distinct { columns.toColumnSet() }

/**
* {@include [DistinctDocs]}
* {@set PHRASE_ENDING the specified columns}.
* {@set DESCRIPTION It selects the specified columns and keeps only distinct rows based on these selected columns}
* {@set [DistinctDocs.DISTINCT_PARAM] @param [columns] The names of the columns to select
* and to consider for evaluating distinct rows.}
* {@set [DISTINCT_RETURN] @return A new [DataFrame] containing only selected columns and distinct rows.}
*/
@Deprecated(DEPRECATED_ACCESS_API)
@AccessApiOverload
Expand All @@ -87,7 +104,10 @@ public fun <T> DataFrame<T>.distinct(vararg columns: AnyColumnReference): DataFr

/**
* {@include [DistinctDocs]}
* {@set NAME DistinctBy}
* {@set PHRASE_ENDING the specified columns}.
Copy link
Collaborator

@AndreiKingsley AndreiKingsley Dec 9, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

change to [\columns] here and in other places

* {@set [DistinctDocs.DISTINCT_PARAM] @param [columns]
Copy link
Collaborator Author

@Allex-Nik Allex-Nik Dec 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I specified this explicitly for this and the following functions (instead of keeping the default option in the common section in DistinctDocs) to avoid the issue with [columns] I mentioned in the description of the PR.

* The names of the columns to consider for evaluating distinct rows.}
*/
@Deprecated(DEPRECATED_ACCESS_API)
@AccessApiOverload
Expand All @@ -96,13 +116,19 @@ public fun <T> DataFrame<T>.distinctBy(vararg columns: KProperty<*>): DataFrame<

/**
* {@include [DistinctDocs]}
* {@set NAME DistinctBy}
* {@set PHRASE_ENDING the specified columns}.
* {@set [DistinctDocs.DISTINCT_PARAM] @param [columns]
* The names of the columns to consider for evaluating distinct rows.}
*/
public fun <T> DataFrame<T>.distinctBy(vararg columns: String): DataFrame<T> = distinctBy { columns.toColumnSet() }

/**
* {@include [DistinctDocs]}
* {@set NAME DistinctBy}
* {@set PHRASE_ENDING the specified columns}.
* {@set [DistinctDocs.DISTINCT_PARAM] @param [columns]
* The names of the columns to consider for evaluating distinct rows.}
*/
@Deprecated(DEPRECATED_ACCESS_API)
@AccessApiOverload
Expand All @@ -111,7 +137,10 @@ public fun <T> DataFrame<T>.distinctBy(vararg columns: AnyColumnReference): Data

/**
* {@include [DistinctDocs]}
* {@set NAME DistinctBy}
* {@set PHRASE_ENDING the specified columns}.
* {@set [DistinctDocs.DISTINCT_PARAM] @param [columns]
* The names of the columns to consider for evaluating distinct rows.}
*/
public fun <T, C> DataFrame<T>.distinctBy(columns: ColumnsSelector<T, C>): DataFrame<T> {
val cols = get(columns)
Expand Down
3 changes: 3 additions & 0 deletions core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/DocumentationUrls.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,9 @@ internal interface DocumentationUrls {
/** <a href="{@include [Url]}/distinct.html">See `distinct` on the documentation website.</a> */
interface Distinct

/** <a href="{@include [Url]}/distinct.html#distinctby">See `distinctBy` on the documentation website.</a> */
interface DistinctBy

/** <a href="{@include [Url]}/flatten.html">See `flatten` on the documentation website.</a> */
interface Flatten

Expand Down