Adding codespans for code reference in KDocs

KDOC_GUIDELINES.md

@@ -14,6 +14,7 @@ This document outlines the guidelines for writing KDocs in the Kotlin DataFrame
       * [URLs](#urls)
       * [Utils](#utils)
   * [Kotlin DataFrame Operations KDoc Structure](#kotlin-dataframe-operations-kdoc-structure)
+    * [Referring to code](#referring-to-code)
     * [General Template](#general-template)
       * [First line](#first-line)
       * [Body](#body)
@@ -275,6 +276,46 @@ as arguments and return simple value, `DataFrame`, `DataRow` or `DataColumn`.
    [special notation](./core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/DslGrammar.kt).
    Add a reference to the operation Grammar in each related class and method KDoc.
 
+### Referring to code
+
+Whenever a KDoc refers to something that is code — a function, class, property, parameter, type,
+keyword, literal, or a snippet of an expression — write it in a code span.
+
+For linked references, this means putting the link label inside `` ` `` tags:
+
+```kotlin
+/** [`select`][DataFrame.select] */ // ✅
+/** [select][DataFrame.select] */   // ❌
+```
+
+References inside `[]` are currently rendered as `<code>` by IntelliJ, but that's an implementation
+detail that may change, and it doesn't hold for Dokka.
+Writing the code span explicitly keeps the rendering the same everywhere.
+
+Note that this only applies to labels that are actually code.
+Prose labels (those that are part of the flow of the sentence) stay as they are, even when they link to code:
+
+```kotlin
+/** ... takes the last [row][DataRow] of each group ... */              // ✅ "row" is prose here
+/** ... see the [Columns Selection DSL][ColumnsSelectionDsl] ... */     // ✅ prose label
+```
+
+Links to [KDoc-helpers](#kodex--kdoc-helpers) are prose too: they're KDoc holders, not code,
+even though they're written as Kotlin declarations.
+
+```kotlin
+/** ### Check out: [Grammar][ConvertDocs.Grammar] */                  // ✅ a KDoc-topic
+/** For the full list, see [SupportedTypes][ConvertDocs.SupportedTypes]. */ // ✅
+```
+
+This is about the *label*, not the target.
+A grammar definition reference like `` [`colSelector`][ColumnSelectorDef] `` keeps its code span:
+the label is a parameter name, the KDoc-helper just happens to be where it's described.
+
+Unlinked code, like `` `null` `` or `` `String` ``, gets a code span too.
+Single-reference links, like `[DataFrame]`, cannot be wrapped —
+`` [`DataFrame`] `` does not resolve — so leave those alone.
+
 ### General Template
 
 The generalized template for all operations:
@@ -613,8 +654,8 @@ But keep these things in mind:
   begins and ends with a space but does not consist entirely of whitespace, a single space is removed from the front
   and the back. So be careful writing things like `` ` { ` `` and add extra spaces if needed.
 - In IntelliJ, references inside `[]` are automatically formatted as `<code>` when rendered to HTML at the moment.
-  This may change in the future,
-  so if you want to be sure it looks like code, you can write it like: `` [`function`][ref.to.function]  ``
+  This may change in the future, so always write the code span yourself:
+  `` [`function`][ref.to.function] `` (see [Referring to code](#referring-to-code)).
 - Having multiple `[]` references and code spans in the same line breaks rendering in
   IntelliJ ([KT-55073](https://youtrack.jetbrains.com/issue/KT-55073/Improve-KDoc-experience#focus=Comments-27-6854785.0-0)).
   This can be avoided by providing aliases to each reference.

build-logic/src/main/kotlin/dfbuild/buildExampleProjects/generateTestCase.kt

@@ -14,7 +14,7 @@ typealias Code = String
  *
  * This implementation of [dfbuild.buildExampleProjects.TestBuildingExampleProjects]
  * should be written into 'build/generated/testBuildingExamples' and included in the
- * 'testBuildingExamples' [SourceSet][org.gradle.api.tasks.SourceSet].
+ * 'testBuildingExamples' [`SourceSet`][org.gradle.api.tasks.SourceSet].
  */
 @Language("kt")
 fun generateTestCase(

build-logic/src/testBuildingExamples/kotlin/dfbuild/buildExampleProjects/TestBuildingExampleProjects.kt

@@ -17,7 +17,7 @@ import java.io.File
  * Each folder needs to have its own test class so the tests can run in parallel.
  *
  * This class, as well as the generated tests, are automatically registered as
- * the 'testBuildingExamples' [SourceSet][org.gradle.api.tasks.SourceSet] by the
+ * the 'testBuildingExamples' [`SourceSet`][org.gradle.api.tasks.SourceSet] by the
  * `dfbuild.buildExampleProjects` convention plugin.
  */
 @Suppress("unused")

core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/DataColumn.kt

@@ -140,7 +140,7 @@ public interface DataColumn<out T> : BaseColumn<T> {
          * For instance, when there are other [DataFrames][DataFrame] present in [values], we'll convert:
          * - `null` -> [DataFrame.empty]`()`
          * - [DataRow] -> single-row [DataFrame]
-         * - [List][List]`<`[DataRow][DataRow]`<*>>` -> multi-row [DataFrame]
+         * - [`List`][List]`<`[`DataRow`][DataRow]`<*>>` -> multi-row [DataFrame]
          *
          * to be able to create a [FrameColumn].
          * There are more conversions for other types as well.

core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/aggregation/AggregateDsl.kt

@@ -51,27 +51,27 @@ import kotlin.reflect.typeOf
  *
  * Predefined shortcuts for the most common statistical aggregation operations on [DataFrame].
  *
- * * [count][DataFrame.count] — calculate the number of rows
+ * * [`count`][DataFrame.count] — calculate the number of rows
  *   (optionally counting only rows that satisfy the given predicate);
- * * [max][DataFrame.max] / [maxOf][DataFrame.maxOf] / [maxFor][DataFrame.maxFor] —
+ * * [`max`][DataFrame.max] / [`maxOf`][DataFrame.maxOf] / [`maxFor`][DataFrame.maxFor] —
  *   calculate the maximum of all values on the selected columns / by a row expression /
  *   for each of the selected columns;
- * * [min][DataFrame.min] / [minOf][DataFrame.minOf] / [minFor][DataFrame.minFor] —
+ * * [`min`][DataFrame.min] / [`minOf`][DataFrame.minOf] / [`minFor`][DataFrame.minFor] —
  *   calculate the minimum of all values on the selected columns / by a row expression /
  *   for each of the selected columns;
- * * [sum][DataFrame.sum] / [sumOf][DataFrame.sumOf] / [sumFor][DataFrame.sumFor] —
+ * * [`sum`][DataFrame.sum] / [`sumOf`][DataFrame.sumOf] / [`sumFor`][DataFrame.sumFor] —
  *   calculate the sum of all values on the selected columns / by a row expression /
  *   for each of the selected columns;
- * * [mean][DataFrame.mean] / [meanOf][DataFrame.meanOf] / [meanFor][DataFrame.meanFor] —
+ * * [`mean`][DataFrame.mean] / [`meanOf`][DataFrame.meanOf] / [`meanFor`][DataFrame.meanFor] —
  *   calculate the mean (average) of all values on the selected columns / by a row expression /
  *   for each of the selected columns;
- * * [std][DataFrame.std] / [stdOf][DataFrame.stdOf] / [stdFor][DataFrame.stdFor] —
+ * * [`std`][DataFrame.std] / [`stdOf`][DataFrame.stdOf] / [`stdFor`][DataFrame.stdFor] —
  *   calculate the standard deviation of all values on the selected columns / by a row expression /
  *   for each of the selected columns;
- * * [median][DataFrame.median] / [medianOf][DataFrame.medianOf] / [medianFor][DataFrame.medianFor] —
+ * * [`median`][DataFrame.median] / [`medianOf`][DataFrame.medianOf] / [`medianFor`][DataFrame.medianFor] —
  *   calculate the median of all values on the selected columns / by a row expression /
  *   for each of the selected columns;
- * * [percentile][DataFrame.percentile] / [percentileOf][DataFrame.percentileOf] / [percentileFor][DataFrame.percentileFor] —
+ * * [`percentile`][DataFrame.percentile] / [`percentileOf`][DataFrame.percentileOf] / [`percentileFor`][DataFrame.percentileFor] —
  *   calculate a specified percentile of all values on the selected columns / by a row expression /
  *   for each of the selected columns.
  *
@@ -81,12 +81,12 @@ internal typealias DataFrameAggregationStatistics = Nothing
 
 /**
  * {@get [AGGREGATE_DSL_TYPE]} allows to compute statistics on the {@get [OPERATING_COLUMNS]}
- * and store the results as a new column using [into][AggregateDsl.into]. {@get [APPLY_NOTE]}
+ * and store the results as a new column using [`into`][AggregateDsl.into]. {@get [APPLY_NOTE]}
  *
  *
  * The resulting {@get [RESULT_TYPE]} has the same structure as the original
  * {@get [RECEIVER]};
- * instead of the groups, there are new columns of aggregated values created with [into][AggregateDsl.into].
+ * instead of the groups, there are new columns of aggregated values created with [`into`][AggregateDsl.into].
  *
  * You can use any of [DataFrame Aggregation Statistics][DataFrameAggregationStatistics]
  * or any custom aggregation function.
@@ -97,7 +97,7 @@ internal interface AggregateDslDocs {
 
     /**
      * Aggregated values can be either simple values, [data rows][DataRow] or even
-     * [data frames][DataFrame]. Including them in the result using [into][AggregateDsl.into] will lead
+     * [data frames][DataFrame]. Including them in the result using [`into`][AggregateDsl.into] will lead
      * to creating [value column][ValueColumn],
      * [column group][ColumnGroup] or [frame column][FrameColumn] respectively
      * in the resulting {@get [RESULT_TYPE]} while preserving the original structure at higher levels.

core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/aggregation/AggregateGroupedDsl.kt

@@ -18,20 +18,20 @@ import org.jetbrains.kotlinx.dataframe.documentation.ExcludeFromSources
  * {@set [AggregateDslDocs.RESULT_TYPE] [DataFrame]}
  * {@set [AggregateDslDocs.OPERATING_COLUMNS] columns within groups in [GroupBy]}
  *
- * It allows [pivoting][DataFrame.pivot] inside [aggregate][Grouped.aggregate] via corresponding methods:
- * * [pivot][AggregateGroupedDsl.pivot]
- * * [pivotCounts][AggregateGroupedDsl.pivotCounts]
- * * [pivotMatches][AggregateGroupedDsl.pivotMatches]
+ * It allows [pivoting][DataFrame.pivot] inside [`aggregate`][Grouped.aggregate] via corresponding methods:
+ * * [`pivot`][AggregateGroupedDsl.pivot]
+ * * [`pivotCounts`][AggregateGroupedDsl.pivotCounts]
+ * * [`pivotMatches`][AggregateGroupedDsl.pivotMatches]
  *
- * Pivoting inside [aggregate][Grouped.aggregate] is useful for counting
+ * Pivoting inside [`aggregate`][Grouped.aggregate] is useful for counting
  * cross-group matrix-like statistics.
  */
 @ExcludeFromSources
 internal typealias AggregateGroupedDslDocsSnippet = Nothing
 
 /**
  * A specialized [AggregateDsl]
- * used in [GroupBy.aggregate][Grouped.aggregate] method; allows
+ * used in [`GroupBy.aggregate`][Grouped.aggregate] method; allows
  * [pivoting][DataFrame.pivot] inside its body.
  *
  * {@include [AggregateGroupedDslDocsSnippet]}

core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/aliases.kt

@@ -143,8 +143,8 @@ public typealias ColumnsSelector<T, C> = Selector<ColumnsSelectionDsl<T>, Column
  * The lambda has access to the [`DataRow<T>`][DataRow] both as `this` and as `it`,
  * enabling concise and readable conditions.
  *
- * Commonly used in operations such as [filter][org.jetbrains.kotlinx.dataframe.api.filter],
- * [drop][org.jetbrains.kotlinx.dataframe.api.drop], and others.
+ * Commonly used in operations such as [`filter`][org.jetbrains.kotlinx.dataframe.api.filter],
+ * [`drop`][org.jetbrains.kotlinx.dataframe.api.drop], and others.
  *
  * Equivalent to:
  * ```kotlin

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

@@ -24,7 +24,7 @@ public interface ColumnSelectionDsl<out T> : ColumnsContainer<T> {
      * Retrieves the value of this [ColumnReference] or [-Accessor][ColumnAccessor] from
      * the [DataFrame].
      *
-     * This is a shorthand for [get][ColumnsContainer.get]`(myColumn)`.
+     * This is a shorthand for [`get`][ColumnsContainer.get]`(myColumn)`.
      * @throws [IllegalArgumentException] if the column is not found.
      */
     private typealias CommonColumnReferenceInvokeDocs = Nothing
@@ -49,7 +49,7 @@ public interface ColumnSelectionDsl<out T> : ColumnsContainer<T> {
 
     /**
      * Retrieves the value of this [ColumnPath] from the [DataFrame].
-     * This is a shorthand for [getColumn][ColumnsContainer.getColumn]`(myColumnPath)` and
+     * This is a shorthand for [`getColumn`][ColumnsContainer.getColumn]`(myColumnPath)` and
      * is most often used in combination with `operator fun String.get(column: String)`, {@comment cannot point to the right function.}
      * for instance:
      * ```kotlin
@@ -65,7 +65,7 @@ public interface ColumnSelectionDsl<out T> : ColumnsContainer<T> {
     /**
      * Retrieves the value of this [KProperty Accessor][KProperty] from the [DataFrame].
      *
-     * This is a shorthand for [get][ColumnsContainer.get]`(MyType::myColumn)`.
+     * This is a shorthand for [`get`][ColumnsContainer.get]`(MyType::myColumn)`.
      * @throws [IllegalArgumentException] if the column is not found.
      */
     private typealias CommonKPropertyInvokeDocs = Nothing
@@ -99,7 +99,7 @@ public interface ColumnSelectionDsl<out T> : ColumnsContainer<T> {
      *
      * This is a shorthand for
      *
-     * [get][ColumnsContainer.get]`(MyType::myColumnGroup).`[asColumnGroup][asColumnGroup]`().`[get][ColumnsContainer.get]`(MyOtherType::myOtherColumn)`
+     * [`get`][ColumnsContainer.get]`(MyType::myColumnGroup).`[`asColumnGroup`][asColumnGroup]`().`[`get`][ColumnsContainer.get]`(MyOtherType::myOtherColumn)`
      *
      * and can instead be written as
      *
@@ -170,7 +170,7 @@ public interface ColumnSelectionDsl<out T> : ColumnsContainer<T> {
     /**
      * Retrieves the value of the column with this name from the [DataFrame]. This can be
      * both typed and untyped.
-     * This is a shorthand for [get][ColumnsContainer.get]`("myColumnName")` and can be
+     * This is a shorthand for [`get`][ColumnsContainer.get]`("myColumnName")` and can be
      * written as `"myColumnName"<MyColumnType>()` instead.
      *
      * @throws [IllegalArgumentException] if there is no column with this name.
@@ -184,7 +184,7 @@ public interface ColumnSelectionDsl<out T> : ColumnsContainer<T> {
     /**
      * Retrieves the value of the column with this name from the [DataFrame]. This can be
      * both typed and untyped.
-     * This is a shorthand for [get][ColumnsContainer.get]`("myColumnName")` and can be
+     * This is a shorthand for [`get`][ColumnsContainer.get]`("myColumnName")` and can be
      * written as `"myColumnName"()` instead.
      *
      * @throws [IllegalArgumentException] if there is no column with this name.

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

@@ -37,7 +37,7 @@ public annotation class ColumnsSelectionDslMarker
 /**
  * ## Columns Selection DSL
  * {@include [SelectingColumns.ColumnsSelectionDsl.ColumnsSelectionDslWithExample]}
- * {@set [SelectingColumns.OPERATION] [select][DataFrame.select]}
+ * {@set [SelectingColumns.OPERATION] [`select`][DataFrame.select]}
  *
  * @comment This interface be safely cast to [SingleColumn] across the library because it's always
  * implemented in combination with [DataFrameReceiver] which is a [SingleColumn] itself.
@@ -391,9 +391,9 @@ public interface ColumnsSelectionDsl<out T> : // SingleColumn<DataRow<T>>
      * @include [SelectColumnsSelectionDsl.CommonSelectDocs]
      * @set [SelectColumnsSelectionDsl.CommonSelectDocs.EXAMPLE]
      *
-     * `df.`[select][DataFrame.select]` { myColGroup.`[`select`][SingleColumn.select]`  { someCol  `[`and`][ColumnsSelectionDsl.and]` `[`colsOf`][SingleColumn.colsOf]`<`[`String`][String]`>() } }`
+     * `df.`[`select`][DataFrame.select]` { myColGroup.`[`select`][SingleColumn.select]`  { someCol  `[`and`][ColumnsSelectionDsl.and]` `[`colsOf`][SingleColumn.colsOf]`<`[`String`][String]`>() } }`
      *
-     * `df.`[select][DataFrame.select]`  { myColGroup  `[`{`][SingleColumn.select]`  colA  `[and][ColumnsSelectionDsl.and]`  colB  `[`}`][SingleColumn.select]` }`
+     * `df.`[`select`][DataFrame.select]`  { myColGroup  `[`{`][SingleColumn.select]`  colA  `[`and`][ColumnsSelectionDsl.and]`  colB  `[`}`][SingleColumn.select]` }`
      */
     public operator fun <C, R> SingleColumn<DataRow<C>>.invoke(selector: ColumnsSelector<C, R>): ColumnSet<R> =
         select(selector)
@@ -402,9 +402,9 @@ public interface ColumnsSelectionDsl<out T> : // SingleColumn<DataRow<T>>
      * @include [SelectColumnsSelectionDsl.CommonSelectDocs]
      * @set [SelectColumnsSelectionDsl.CommonSelectDocs.EXAMPLE]
      *
-     * `df.`[select][DataFrame.select]` { Type::myColGroup.`[`select`][KProperty.select]`  { someCol  `[`and`][ColumnsSelectionDsl.and]` `[`colsOf`][SingleColumn.colsOf]`<`[`String`][String]`>() } }`
+     * `df.`[`select`][DataFrame.select]` { Type::myColGroup.`[`select`][KProperty.select]`  { someCol  `[`and`][ColumnsSelectionDsl.and]` `[`colsOf`][SingleColumn.colsOf]`<`[`String`][String]`>() } }`
      *
-     * `df.`[select][DataFrame.select]`  { DataSchemaType::myColGroup  `[`{`][KProperty.select]`  colA  `[`and`][ColumnsSelectionDsl.and]`  colB  `[`}`][KProperty.select]` }`
+     * `df.`[`select`][DataFrame.select]`  { DataSchemaType::myColGroup  `[`{`][KProperty.select]`  colA  `[`and`][ColumnsSelectionDsl.and]`  colB  `[`}`][KProperty.select]` }`
      */
     @Deprecated(DEPRECATED_ACCESS_API)
     @AccessApiOverload
@@ -415,23 +415,23 @@ public interface ColumnsSelectionDsl<out T> : // SingleColumn<DataRow<T>>
      * @include [SelectColumnsSelectionDsl.CommonSelectDocs]
      * @set [SelectColumnsSelectionDsl.CommonSelectDocs.EXAMPLE]
      *
-     * `df.`[select][DataFrame.select]` { "myColGroup".`[`select`][String.select]`  { someCol  `[`and`][ColumnsSelectionDsl.and]` `[`colsOf`][SingleColumn.colsOf]`<`[`String`][String]`>() } }`
+     * `df.`[`select`][DataFrame.select]` { "myColGroup".`[`select`][String.select]`  { someCol  `[`and`][ColumnsSelectionDsl.and]` `[`colsOf`][SingleColumn.colsOf]`<`[`String`][String]`>() } }`
      *
-     * `df.`[select][DataFrame.select]`  { "myColGroup"  `[`{`][String.select]`  colA  `[`and`][ColumnsSelectionDsl.and]`  colB  `[`}`][String.select]` }`
+     * `df.`[`select`][DataFrame.select]`  { "myColGroup"  `[`{`][String.select]`  colA  `[`and`][ColumnsSelectionDsl.and]`  colB  `[`}`][String.select]` }`
      */
     public operator fun <R> String.invoke(selector: ColumnsSelector<*, R>): ColumnSet<R> = select(selector)
 
     /**
      * @include [SelectColumnsSelectionDsl.CommonSelectDocs]
      * @set [SelectColumnsSelectionDsl.CommonSelectDocs.EXAMPLE]
      *
-     * `df.`[select][DataFrame.select]` { "pathTo"["myColGroup"].`[`select`][ColumnPath.select]`  { someCol  `[`and`][ColumnsSelectionDsl.and]` `[`colsOf`][SingleColumn.colsOf]`<`[`String`][String]`>() } }`
+     * `df.`[`select`][DataFrame.select]` { "pathTo"["myColGroup"].`[`select`][ColumnPath.select]`  { someCol  `[`and`][ColumnsSelectionDsl.and]` `[`colsOf`][SingleColumn.colsOf]`<`[`String`][String]`>() } }`
      *
-     * `df.`[select][DataFrame.select]`  { "pathTo"["myColGroup"]  `[`{`][ColumnPath.select]`  colA  `[`and`][ColumnsSelectionDsl.and]`  colB  `[`}`][ColumnPath.select]` }`
+     * `df.`[`select`][DataFrame.select]`  { "pathTo"["myColGroup"]  `[`{`][ColumnPath.select]`  colA  `[`and`][ColumnsSelectionDsl.and]`  colB  `[`}`][ColumnPath.select]` }`
      *
-     * `df.`[select][DataFrame.select]`  {  `[`pathOf`][pathOf]`("pathTo", "myColGroup").`[`select`][ColumnPath.select]`  { someCol  `[`and`][ColumnsSelectionDsl.and]` `[`colsOf`][SingleColumn.colsOf]`<`[`String`][String]`>() } }`
+     * `df.`[`select`][DataFrame.select]`  {  `[`pathOf`][pathOf]`("pathTo", "myColGroup").`[`select`][ColumnPath.select]`  { someCol  `[`and`][ColumnsSelectionDsl.and]` `[`colsOf`][SingleColumn.colsOf]`<`[`String`][String]`>() } }`
      *
-     * `df.`[select][DataFrame.select]`  {  `[`pathOf`][pathOf]`("pathTo", "myColGroup")`[`() {`][ColumnPath.select]`  someCol  `[`and`][ColumnsSelectionDsl.and]` `[`colsOf`][SingleColumn.colsOf]`<`[`String`][String]`>() `[`}`][ColumnPath.select]` }`
+     * `df.`[`select`][DataFrame.select]`  {  `[`pathOf`][pathOf]`("pathTo", "myColGroup")`[`() {`][ColumnPath.select]`  someCol  `[`and`][ColumnsSelectionDsl.and]` `[`colsOf`][SingleColumn.colsOf]`<`[`String`][String]`>() `[`}`][ColumnPath.select]` }`
      */
     public operator fun <R> ColumnPath.invoke(selector: ColumnsSelector<*, R>): ColumnSet<R> = select(selector)