Updating docs processor

core/build.gradle.kts

@@ -154,6 +154,22 @@ tasks.withType<KorroTask> {
     dependsOn(copySamplesOutputs)
 }
 
+// This task installs the pre-commit hook to the local machine the first time the project is built
+// The pre-commit hook contains the command to run processKDocsMain before each commit
+val installGitPreCommitHook by tasks.creating(Copy::class) {
+    doNotTrackState(/* reasonNotToTrackState = */ "Fails on TeamCity otherwise.")
+
+    from(File(rootProject.rootDir, "gradle/scripts/pre-commit"))
+    into(File(rootProject.rootDir, ".git/hooks"))
+    fileMode = 755
+}
+tasks.named("assemble") {
+    dependsOn(installGitPreCommitHook)
+}
+
+// region docPreprocessor
+
+// This task is used to add all generated sources (from processKDocsMain) to git
 val generatedSourcesFolderName = "generated-sources"
 val addGeneratedSourcesToGit by tasks.creating(GitTask::class) {
     directory.set(file("."))
@@ -162,8 +178,8 @@ val addGeneratedSourcesToGit by tasks.creating(GitTask::class) {
 }
 
 // Backup the kotlin source files location
-val kotlinMainSources = kotlin.sourceSets.main.get().kotlin.sourceDirectories
-val kotlinTestSources = kotlin.sourceSets.test.get().kotlin.sourceDirectories
+val kotlinMainSources: FileCollection = kotlin.sourceSets.main.get().kotlin.sourceDirectories
+val kotlinTestSources: FileCollection = kotlin.sourceSets.test.get().kotlin.sourceDirectories
 
 fun pathOf(vararg parts: String) = parts.joinToString(File.separator)
 
@@ -176,12 +192,15 @@ val processKDocsMain by creatingProcessDocTask(
     processors = listOf(
         INCLUDE_DOC_PROCESSOR,
         INCLUDE_FILE_DOC_PROCESSOR,
-        INCLUDE_ARG_DOC_PROCESSOR,
+        ARG_DOC_PROCESSOR,
         COMMENT_DOC_PROCESSOR,
         SAMPLE_DOC_PROCESSOR,
     )
 
+    arguments += ARG_DOC_PROCESSOR_LOG_NOT_FOUND to false
+
     task {
+        group = "KDocs"
         doLast {
             // ensure generated sources are added to git
             addGeneratedSourcesToGit.executeCommand()
@@ -224,6 +243,18 @@ tasks.withType<Jar> {
     }
 }
 
+// If we want to use Dokka, make sure to use the preprocessed sources
+tasks.withType<org.jetbrains.dokka.gradle.AbstractDokkaLeafTask> {
+    dependsOn(processKDocsMain)
+    dokkaSourceSets {
+        all {
+            sourceRoot(processKDocsMain.target.get())
+        }
+    }
+}
+
+// endregion
+
 korro {
     docs = fileTree(rootProject.rootDir) {
         include("docs/StardustDocs/topics/*.md")
@@ -370,13 +401,3 @@ dataframes {
         name = "org.jetbrains.kotlinx.dataframe.samples.api.Repository"
     }
 }
-
-// If we want to use Dokka, make sure to use the preprocessed sources
-tasks.withType<org.jetbrains.dokka.gradle.AbstractDokkaLeafTask> {
-    dependsOn(processKDocsMain)
-    dokkaSourceSets {
-        all {
-            sourceRoot(processKDocsMain.target.get())
-        }
-    }
-}

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

@@ -238,7 +238,7 @@ public interface ColumnsSelectionDsl<out T> : ColumnSelectionDsl<T>, SingleColum
      *
      * #### For example:
      *
-     * {@includeArg [Examples]}
+     * {@getArg [Examples]}
      *
      * @param [condition\] The optional [ColumnFilter] condition that the column must adhere to.
      * @return A [SingleColumn] containing the first column that adheres to the given [condition\].
@@ -327,7 +327,7 @@ public interface ColumnsSelectionDsl<out T> : ColumnSelectionDsl<T>, SingleColum
      *
      * #### For example:
      *
-     * {@includeArg [Examples]}
+     * {@getArg [Examples]}
      *
      * @param [condition\] The optional [ColumnFilter] condition that the column must adhere to.
      * @return A [SingleColumn] containing the last column that adheres to the given [condition\].
@@ -416,7 +416,7 @@ public interface ColumnsSelectionDsl<out T> : ColumnSelectionDsl<T>, SingleColum
      *
      * #### For example:
      *
-     * {@includeArg [Examples]}
+     * {@getArg [Examples]}
      *
      * @param [condition\] The optional [ColumnFilter] condition that the column must adhere to.
      * @return A [SingleColumn] containing the single column that adheres to the given [condition\].
@@ -505,7 +505,7 @@ public interface ColumnsSelectionDsl<out T> : ColumnSelectionDsl<T>, SingleColum
      *
      * #### For example:
      *
-     * `df.`[select][DataFrame.select]` { `{@includeArg [CommonSubsetOfColumnsDocs.Example]}` }`
+     * `df.`[select][DataFrame.select]` { `{@getArg [CommonSubsetOfColumnsDocs.Example]}` }`
      *
      * @param [endInclusive\] The last column in the subset.
      * @receiver The first column in the subset.
@@ -717,9 +717,9 @@ public interface ColumnsSelectionDsl<out T> : ColumnSelectionDsl<T>, SingleColum
      *
      * #### For example:
      *
-     * `df.`[select][select]` { `[col][col]`({@includeArg [CommonColDocs.Arg]}) }`
+     * `df.`[select][select]` { `[col][col]`({@getArg [CommonColDocs.Arg]}) }`
      *
-     * `df.`[select][select]` { myColGroup.`[col][col]`<SomeType>({@includeArg [CommonColDocs.Arg]}) }`
+     * `df.`[select][select]` { myColGroup.`[col][col]`<SomeType>({@getArg [CommonColDocs.Arg]}) }`
      *
      * @return A [ColumnAccessor] for the column with the given argument.
      * @see [column\]
@@ -1020,9 +1020,9 @@ public interface ColumnsSelectionDsl<out T> : ColumnSelectionDsl<T>, SingleColum
      *
      * #### For example:
      *
-     * `df.`[select][select]` { `[colGroup][colGroup]`({@includeArg [CommonColGroupDocs.Arg]}) }`
+     * `df.`[select][select]` { `[colGroup][colGroup]`({@getArg [CommonColGroupDocs.Arg]}) }`
      *
-     * `df.`[select][select]` { myColGroup.`[colGroup][colGroup]`<SomeType>({@includeArg [CommonColGroupDocs.Arg]}) }`
+     * `df.`[select][select]` { myColGroup.`[colGroup][colGroup]`<SomeType>({@getArg [CommonColGroupDocs.Arg]}) }`
      *
      * @return A [ColumnAccessor] for the column group with the given argument.
      * @see [columnGroup\]
@@ -1327,9 +1327,9 @@ public interface ColumnsSelectionDsl<out T> : ColumnSelectionDsl<T>, SingleColum
      * an accessor for a frame column inside a [ColumnGroup].
      *
      * #### For example:
-     * `df.`[select][select]` { `[frameCol][frameCol]`({@includeArg [CommonFrameColDocs.Arg]}) }`
+     * `df.`[select][select]` { `[frameCol][frameCol]`({@getArg [CommonFrameColDocs.Arg]}) }`
      *
-     * `df.`[select][select]` { myColGroup.`[frameCol][frameCol]`<SomeType>({@includeArg [CommonFrameColDocs.Arg]}) }`
+     * `df.`[select][select]` { myColGroup.`[frameCol][frameCol]`<SomeType>({@getArg [CommonFrameColDocs.Arg]}) }`
      *
      * @return A [ColumnAccessor] for the frame column with the given argument.
      * @see [frameColumn\]
@@ -1636,7 +1636,7 @@ public interface ColumnsSelectionDsl<out T> : ColumnSelectionDsl<T>, SingleColum
      *
      * #### Examples for this overload:
      *
-     * {@includeArg [CommonColsDocs.Examples]}
+     * {@getArg [CommonColsDocs.Examples]}
      *
      */
     private interface CommonColsDocs {
@@ -1664,7 +1664,7 @@ public interface ColumnsSelectionDsl<out T> : ColumnSelectionDsl<T>, SingleColum
          *
          * #### Examples for this overload:
          *
-         * {@includeArg [CommonColsDocs.Examples][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.CommonColsDocs.Examples]}
+         * {@getArg [CommonColsDocs.Examples][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.CommonColsDocs.Examples]}
          *
          *
          * @param [predicate\] A [ColumnFilter function][ColumnFilter] that takes a [ColumnReference] and returns a [Boolean].
@@ -1695,11 +1695,11 @@ public interface ColumnsSelectionDsl<out T> : ColumnSelectionDsl<T>, SingleColum
          *
          * #### Examples for this overload:
          *
-         * {@includeArg [CommonColsDocs.Examples][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.CommonColsDocs.Examples]}
+         * {@getArg [CommonColsDocs.Examples][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.CommonColsDocs.Examples]}
          *
          *
-         * @param [firstCol\] A {@includeArg [AccessorType]} that points to a column.
-         * @param [otherCols\] Optional additional {@includeArg [AccessorType]}s that point to columns.
+         * @param [firstCol\] A {@getArg [AccessorType]} that points to a column.
+         * @param [otherCols\] Optional additional {@getArg [AccessorType]}s that point to columns.
          * @return A [ColumnSet] containing the columns that [firstCol\] and [otherCols\] point to.
          */
         interface Vararg {
@@ -3777,7 +3777,7 @@ public interface ColumnsSelectionDsl<out T> : ColumnSelectionDsl<T>, SingleColum
      *
      * #### Examples for this overload:
      *
-     * {@includeArg [CommonAllDocs.Examples]}
+     * {@getArg [CommonAllDocs.Examples]}
      *
      * @see [cols\]
      */
@@ -3940,7 +3940,7 @@ public interface ColumnsSelectionDsl<out T> : ColumnSelectionDsl<T>, SingleColum
      *
      * #### Examples for this overload:
      *
-     * {@includeArg [CommonRecursivelyDocs.Examples]}
+     * {@getArg [CommonRecursivelyDocs.Examples]}
      *
      * @param [includeTopLevel\] Whether to include the top-level columns in the result. `true` by default.
      */

core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/convertTo.kt

@@ -17,7 +17,7 @@ import kotlin.reflect.KType
 import kotlin.reflect.typeOf
 
 /**
- * Specifies how to handle columns in original dataframe that were not mathced to any column in destination dataframe schema.
+ * Specifies how to handle columns in original dataframe that were not matched to any column in destination dataframe schema.
  */
 public enum class ExcessiveColumns {
     /**

core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/update.kt

@@ -458,7 +458,7 @@ private interface UpdatePerColMap
  *
  * For example:
  *
- * `val defaults = {@includeArg [CommonUpdatePerColMapDoc]}`
+ * `val defaults = {@getArg [CommonUpdatePerColMapDoc]}`
  *
  * `df.`[update][update]` { name and age }.`[where][Update.where]` { ... }.`[perCol][perCol]`(defaults)`
  *
@@ -734,11 +734,11 @@ public fun <T> DataFrame<T>.update(
     update(*headPlusArray(firstCol, cols)).with(expression)
 
 /**
- * Specific version of [with] that simply sets the value of each selected row to {@includeArg [CommonSpecificWithDocFirstArg]}.
+ * Specific version of [with] that simply sets the value of each selected row to {@getArg [CommonSpecificWithDocFirstArg]}.
  *
  * For example:
  *
- * `df.`[update][update]` { id }.`[where][Update.where]` { it < 0 }.`{@includeArg [CommonSpecificWithDocSecondArg]}`
+ * `df.`[update][update]` { id }.`[where][Update.where]` { it < 0 }.`{@getArg [CommonSpecificWithDocSecondArg]}`
  */
 private interface CommonSpecificWithDoc
 

core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/DocumentationUrls.kt

@@ -4,7 +4,7 @@ internal interface DocumentationUrls {
 
     interface NameArg
 
-    /** See {@includeArg [NameArg]} on the documentation website. */
+    /** See {@getArg [NameArg]} on the documentation website. */
     interface Text
 
     /** https://kotlin.github.io/dataframe */

core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/ExpressionsGivenColumn.kt

@@ -13,7 +13,7 @@ import org.jetbrains.kotlinx.dataframe.ColumnExpression as DfColumnExpression
 internal interface ExpressionsGivenColumn {
 
     /**
-     * The key for an @arg that will define the operation name for the examples below.
+     * The key for an @setArg that will define the operation name for the examples below.
      * Make sure to [alias][your examples].
      */
     interface OperationArg

core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/ExpressionsGivenDataFrame.kt

@@ -22,7 +22,7 @@ internal interface ExpressionsGivenDataFrame {
          *
          * For example:
          *
-         * {@includeArg [OperationArg]}` { `[select][DataFrame.select]` { lastName } }`
+         * {@getArg [OperationArg]}` { `[select][DataFrame.select]` { lastName } }`
          */
         interface WithExample
     }

core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/ExpressionsGivenRow.kt

@@ -32,7 +32,7 @@ import org.jetbrains.kotlinx.dataframe.RowValueExpression as DfRowValueExpressio
 internal interface ExpressionsGivenRow {
 
     /**
-     * The key for an @arg that will define the operation name for the examples below.
+     * The key for an @setArg that will define the operation name for the examples below.
      * Make sure to [alias][your examples].
      */
     interface OperationArg

core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/ExpressionsGivenRowAndColumn.kt

@@ -13,7 +13,7 @@ import org.jetbrains.kotlinx.dataframe.RowColumnExpression as DfRowColumnExpress
 internal interface ExpressionsGivenRowAndColumn {
 
     /**
-     * The key for an @arg that will define the operation name for the examples below.
+     * The key for an @setArg that will define the operation name for the examples below.
      * Make sure to [alias][your examples].
      */
     interface OperationArg

core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/SelectingColumns.kt

@@ -64,7 +64,7 @@ internal interface SelectingColumnsLink
 internal interface SelectingColumns {
 
     /**
-     * The key for an @arg that will define the operation name for the examples below.
+     * The key for an @setArg that will define the operation name for the examples below.
      * Make sure to [alias][your examples].
      */
     interface OperationArg

core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/SelectingRows.kt

@@ -22,13 +22,13 @@ import org.jetbrains.kotlinx.dataframe.index
 internal interface SelectingRows {
 
     /**
-     * The key for an @arg that will define the operation name for the examples below.
+     * The key for an @setArg that will define the operation name for the examples below.
      * Make sure to [alias][your examples].
      */
     interface FirstOperationArg
 
     /**
-     * The key for an @arg that will define the operation name for the examples below.
+     * The key for an @setArg that will define the operation name for the examples below.
      * Make sure to [alias][your examples].
      */
     interface SecondOperationArg