KDocs fixes for distinct and distinctBy

[Allex-Nik]

Fixes #1434

The documentation for the distinct function with parameters described functionality of distinctBy: it suggested that distinct removes duplicated rows omitting the fact that it also selects the specified columns and the result contains only these columns.

In this PR I:

• Fixed this issue by changing descriptions of distinct
• Added distinctBy to DocumentationUrls
• Specified the parameter explicitly for every function to avoid incorrect resolution of the columns parameter mentioned in DistinctDocs
  
• Made some other minor fixes

[AndreiKingsley]

@Allex-Nik To avoid this problem with [columns] you can write [\columns] instead. We use this trick in many places.

I'd even say it's better to write [\columns] in such places always.

[AndreiKingsley]

Nice! Please, remove headers and add cross-references for distinct/distinctBy operations

[AndreiKingsley]

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

[Jolanrensen]

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

[Jolanrensen]

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

[Allex-Nik]

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
}

[AndreiKingsley]

change to [\columns] here and in other places

[Jolanrensen]

Specified the parameter explicitly for every function to avoid incorrect resolution of the columns parameter mentioned in DistinctDocs

TL;DR: write it like [columns\]

Long explanation:

Whenever some KDocs is @included, all references mentioned in that doc are expanded to their fully qualified path, if possible. This solves the issue that a reference to [a] in one doc is not necessarily resolvable as [a] in another doc. But it may be resolvable as [a][path.to.a].

If a reference cannot be found, it's left unchanged as [a].

Unfortunately, this system is not perfect (resolving symbols by path in kotlin myself is hard XD), so when you write

/** @param [columns] The names of the columns to consider for evaluating distinct rows. */
interface DistinctDocs

/** @include [DistinctDocs] */
public fun <T> DataFrame<T>.distinctBy...

KoDEx tries to find [columns] in the scope of DistinctDocs, finds it, and expands it to [columns][org.jetbrains.kotlinx.dataframe.columns] before including it at distinctBy().

Luckily, we have the \ escape character :) which allows us to stop KoDEx from doing "clever" things. These are removed from the KDocs in the last phase. These allow you to 'break' tags like \@inlude X, or \$something, or references like \[columns] so they aren't processed anymore :). (You can put the \ anywhere in the reference I believe, actually)

[Jolanrensen]

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 :)

[Jolanrensen]

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.

[Jolanrensen]

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

[Jolanrensen]

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