Adding codespans for code reference in KDocs - #2029
Open
Jolanrensen wants to merge 6 commits into
Open
Conversation
Jolanrensen
force-pushed
the
kdoc-codespans
branch
from
August 11, 2026 15:15
cb526aa to
a490b99
Compare
Contributor
There was a problem hiding this comment.
Pull request overview
Adds explicit code spans to KDoc link labels for consistent IntelliJ and Dokka rendering.
Changes:
- Documents the new KDoc convention.
- Updates code-reference labels across APIs, integrations, samples, and build logic.
- Preserves prose-style labels where appropriate.
Reviewed changes
Copilot reviewed 120 out of 120 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
samples/src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/guides/HsqldbGuide.kt |
Updates JDBC sample KDocs. |
KDOC_GUIDELINES.md |
Documents code-reference formatting. |
examples/projects/kotlin-spark/src/main/kotlin/org/jetbrains/kotlinx/dataframe/examples/spark/typedDataset.kt |
Formats annotation references. |
examples/projects/exposed/src/main/kotlin/org/jetbrains/kotlinx/dataframe/examples/exposed/tables.kt |
Formats annotation reference. |
examples/projects/exposed/src/main/kotlin/org/jetbrains/kotlinx/dataframe/examples/exposed/compatibilityLayer.kt |
Formats Exposed code references. |
examples/projects/dev/kotlin-spark/src/main/kotlin/org/jetbrains/kotlinx/dataframe/examples/spark/typedDataset.kt |
Updates generated Spark example. |
examples/projects/dev/exposed/src/main/kotlin/org/jetbrains/kotlinx/dataframe/examples/exposed/tables.kt |
Updates generated Exposed example. |
examples/projects/dev/exposed/src/main/kotlin/org/jetbrains/kotlinx/dataframe/examples/exposed/compatibilityLayer.kt |
Updates generated compatibility example. |
dataframe-json/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/json.kt |
Formats JSON API type references. |
dataframe-jdbc/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/readJdbc.kt |
Formats ResultSet references. |
dataframe-jdbc/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/db/Sqlite.kt |
Formats SQLite API references. |
dataframe-jdbc/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/db/JdbcToDataFrameConverter.kt |
Formats converter type references. |
dataframe-jdbc/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/db/DuckDb.kt |
Formats SQL-table API references. |
dataframe-jdbc/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/db/DbType.kt |
Formats JDBC conversion references. |
dataframe-csv/src/main/kotlin/org/jetbrains/kotlinx/dataframe/impl/io/readDelim.kt |
Formats parser-option references. |
dataframe-csv/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentationCsv/DelimParams.kt |
Formats delimiter parameter KDocs. |
dataframe-csv/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentationCsv/CommonWriteDelimDocs.kt |
Formats write examples. |
dataframe-csv/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentationCsv/CommonReadDelimDocs.kt |
Formats read examples. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/math/basicStats.kt |
Formats statistics properties. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/impl/TypeUtils.kt |
Formats runtime-type references. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/impl/schema/DataFrameSchemaImpl.kt |
Formats schema comparison reference. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/impl/io/FastDoubleParser.kt |
Formats parser references. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/impl/columns/TransformableColumnSet.kt |
Formats transformation examples. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/impl/columns/constructors.kt |
Formats column type references. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/impl/api/parse.kt |
Formats parser implementation references. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/impl/aggregation/aggregators/multipleColumnsHandlers/TwoStepMultipleColumnsHandler.kt |
Formats aggregation references. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/impl/aggregation/aggregators/AggregatorInputHandler.kt |
Formats value-type properties. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/impl/aggregation/aggregators/AggregatorAggregationHandler.kt |
Formats aggregation type references. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/impl/aggregation/aggregators/Aggregator.kt |
Formats aggregator generic types. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/impl/aggregation/aggregators/aggregationHandlers/SelectingAggregationHandler.kt |
Formats nullability reference. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/impl/aggregation/aggregators/aggregationHandlers/ReducingAggregationHandler.kt |
Formats nullability reference. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/impl/aggregation/aggregators/aggregationHandlers/HybridAggregationHandler.kt |
Formats nullability reference. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/UnifyingNumbers.kt |
Formats nullable type reference. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/topics.kt |
Formats operation reference. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/snippets.kt |
Formats parser property reference. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/SelectingRows.kt |
Formats row-selection examples. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/SelectingColumns.kt |
Formats column-selection examples. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/NaN.kt |
Formats NaN operations. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/NA.kt |
Formats NA operations. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/ExpressionsGivenRowAndColumn.kt |
Formats expression example. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/ExpressionsGivenRow.kt |
Formats row-expression operations. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/ExpressionsGivenDataFrame.kt |
Formats DataFrame expression example. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/ExpressionsGivenColumn.kt |
Formats column-expression examples. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/DslGrammarTemplateColumnsSelectionDsl.kt |
Formats DSL type reference. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/CommonTakeAndDropWhileDocs.kt |
Formats take/drop examples. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/CommonTakeAndDropDocs.kt |
Formats take/drop examples. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/CommonMinMaxDocs.kt |
Formats reduction operations. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/DataColumn.kt |
Formats list and row types. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/columns/ValueColumn.kt |
Formats column properties. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/columns/SingleColumn.kt |
Formats type property. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/columns/ColumnReference.kt |
Formats type property. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/columns/ColumnAccessor.kt |
Formats type property. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/codeGen/Marker.kt |
Formats enum constants. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/codeGen/CodeWithTypeCastGenerator.kt |
Formats nullable type reference. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/withoutNulls.kt |
Formats DSL examples. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/valueCols.kt |
Formats value-column examples. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/valueCol.kt |
Formats value-column accessor examples. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/update.kt |
Formats update API KDocs. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/ungroup.kt |
Formats operation reference. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/typeConversions.kt |
Formats conversion type references. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/sort.kt |
Formats sorting examples. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/single.kt |
Formats single-column examples. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/simplify.kt |
Formats simplify examples. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/select.kt |
Formats selection KDocs. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/rename.kt |
Formats rename operations. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/remove.kt |
Formats operation reference. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/ParserOptions.kt |
Formats parser configuration references. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/Nulls.kt |
Formats null-handling operations. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/none.kt |
Formats empty-selection example. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/NameValueProperty.kt |
Formats compatibility types. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/move.kt |
Formats move operations. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/last.kt |
Formats last-operation references. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/joinWith.kt |
Formats joined-row property. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/join.kt |
Formats join DSL references. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/insert.kt |
Formats insertion operations. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/group.kt |
Formats grouping operation. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/generateCode.kt |
Formats code-generation references. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/gather.kt |
Formats gather operations. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/frameCols.kt |
Formats frame-column examples. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/frameCol.kt |
Formats frame-column accessor examples. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/flatten.kt |
Formats operation reference. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/first.kt |
Formats first-operation references. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/filter.kt |
Formats filtering references. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/expr.kt |
Formats expression examples. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/distinct.kt |
Formats related operations. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/describe.kt |
Formats operation reference. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/cumSum.kt |
Formats numeric types and operation. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/countDistinct.kt |
Formats counting references. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/count.kt |
Formats count and pivot references. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/corr.kt |
Formats correlation operations. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/convertTo.kt |
Formats column path property. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/convert.kt |
Formats conversion operations. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/ColumnsSelectionDsl.kt |
Formats DSL examples. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/ColumnSelectionDsl.kt |
Formats shorthand operations. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/columnRange.kt |
Formats selection example. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/colsOfKind.kt |
Formats kind-selection examples. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/colsInGroups.kt |
Formats grouped-column examples. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/colGroups.kt |
Formats column-group examples. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/colGroup.kt |
Formats group accessor examples. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/col.kt |
Formats column accessor examples. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/and.kt |
Formats selection-composition examples. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/add.kt |
Formats add-operation properties. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/aliases.kt |
Formats row-filter operation references. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/aggregation/AggregateGroupedDsl.kt |
Formats grouped aggregation operations. |
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/aggregation/AggregateDsl.kt |
Formats aggregation operation catalog. |
build-logic/src/testBuildingExamples/kotlin/dfbuild/buildExampleProjects/TestBuildingExampleProjects.kt |
Formats Gradle SourceSet reference. |
build-logic/src/main/kotlin/dfbuild/buildExampleProjects/generateTestCase.kt |
Formats Gradle SourceSet reference. |
Suppressed comments (1)
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/impl/columns/TransformableColumnSet.kt:38
singleInternal { }is a code expression, but its link label is still outside a code span. This leaves the example with mixed rendering and contradicts the new linked-code guidance.
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| * Aggregates the data in the multiple given columns and computes a single resulting value. | ||
| * | ||
| * This function calls [aggregator][aggregator] [.aggregateSingleColumn()][Aggregator.aggregateSingleColumn] | ||
| * This function calls [`aggregator`][aggregator] [.aggregateSingleColumn()][Aggregator.aggregateSingleColumn] |
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 120 out of 120 changed files in this pull request and generated no new comments.
Suppressed comments (2)
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/group.kt:35
- The trailing “and,” makes this sentence ungrammatical; removing it lets the following “that return…” clause modify “methods.”
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/impl/schema/DataFrameSchemaImpl.kt:61 - This sentence has a typo: “it the order does not matter” should be “if the order does not matter.”
Jolanrensen
marked this pull request as ready for review
August 11, 2026 16:34
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 120 out of 120 changed files in this pull request and generated no new comments.
Suppressed comments (2)
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/gather.kt:430
Gatherexposeswhere, notfilter(the extension is defined at line 192, and the overview above already linkswhere). Renderingfilteras code now advertises a nonexistent API; use the actual method name for the label.
core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/impl/schema/DataFrameSchemaImpl.kt:61- The sentence still says “it the order does not matter”; this should be “if the order does not matter.”
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #2023
Helps enabling Dokka
I let Claude take this. It wrote a python script to automate adding code-spans, and then it manually reverted changes to prone references like
/** See [Grammar][...Grammar] */which are not considered "code" and thus should be left alone.Before:
After: