Documentation guidelines #1660

AndreiKingsley · 2026-01-19T13:32:37Z

No description provided.

Jolanrensen · 2026-01-19T14:59:20Z

For visibility, we'd need to merge this with https://github.com/Kotlin/dataframe/blob/master/KDOC_PREPROCESSING.md#kodex-conventions-in-dataframe. It may be okay to have two documents:

Kdoc preprocessing
Documenting guide

but they should probably link to each other. A single document could also work

Jolanrensen · 2026-01-19T15:04:26Z

docs/KDocs-Guidelines.md

+
+We use [KoDEx](https://github.com/Jolanrensen/KoDEx) KDocs preprocessor.
+It adds several useful utilities for writing KDocs. Please read about 
+the [KoDEx notation](https://github.com/Jolanrensen/KoDEx/wiki/Notation) before working with Kotlin DataFrame KDocs.


and the other doc. The one in DataFrame contains more practical information, whereas the KoDEx one is more generic

Jolanrensen · 2026-01-19T15:08:40Z

docs/KDocs-Guidelines.md

+One of the best utilities of KoDEx is the ability to reuse common parts of KDocs.
+This can be done by using the 
+[`@include` tag](https://github.com/Jolanrensen/KoDEx/wiki/Notation#include-including-content-from-other-kdocs), 
+which allows you to include a KDoc of another class. 


*another documentable element. Can be a class, interface, type alias, etc.

Jolanrensen · 2026-01-19T15:11:38Z

docs/KDocs-Guidelines.md

+[`@include` tag](https://github.com/Jolanrensen/KoDEx/wiki/Notation#include-including-content-from-other-kdocs), 
+which allows you to include a KDoc of another class. 
+
+There are a lot of interfaces in the project that are only used for including their KDocs


I call those "documentation interfaces". (Though I don't know what to call them when they become type aliases... maybe just "Documentation element"?)

Important to mention is that a documentation interface that a user should be able to reach should nót be excluded.

relevant mention
https://github.com/Kotlin/dataframe/blob/master/KDOC_PREPROCESSING.md#excludefromsources-annotation-excluding-code-content-from-sources

Ok, so my naming proposal:

All exlcuded typealias ..= Nothing or interfaces we use for @include - "KDoc snippets" (or "KDoc fragments").

Not excluded empty entities we use as "topics" we refer to in KDocs (but do not include them) - KDoc navigation anchors.

And let's rename all the entities accordingly:
SelectingColumns - > SelectingColumnsAnchor
RowFilterDescription -> RowFilterSnippet

I believe this will significantly improve KDocs helpers (yeah, I call it like that 😄) structure.

The general one - "KDoc helpers"

"KDoc Snippet" makes sense :)

I don't really like the "Anchor" name, because it's what users will see when they click on it. Ideally the name of 'topics' should just be the title of the topic. AKA interface NaN describes the concept NaN in its KDoc. Maybe these could remain nameless, or follow the backtick convention like for tests, indicating that we see the name of the interface/alias as a title and not something to program with.

I don't like that we give those "placeholder" entities actually meaningful names without highlighting that they are actually dummy

Hmm, I understand... But what do you think of something like:

public interface `DSL Grammar`

Hmm, do you mean "to put all of those entity definitions into backticks"?
It could work!

Jolanrensen · 2026-01-19T15:12:01Z

docs/KDocs-Guidelines.md

+[`ColumnPathCreation` interface](https://github.com/Kotlin/dataframe/blob/master/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/ColumnPathCreation.ktc)
+has a KDoc which describes column path creation behavior. The whole file is excluded from sources,
+but the KDoc is included in other KDocs. 
+z


Jolanrensen · 2026-01-19T15:12:39Z

docs/KDocs-Guidelines.md

+but the KDoc is included in other KDocs. 
+z
+Also, you can use 
+[`@set` and `@get` tags](https://github.com/Jolanrensen/KoDEx/wiki/Notation#set-and-get---setting-and-getting-variables)


$ also means @get https://github.com/Kotlin/dataframe/blob/master/KDOC_PREPROCESSING.md#set-and-get---setting-and-getting-variables

I didn't know it! That's cool, but on the other hand, I'd like to all KoDEx specific stuff starts with @ so user understands where this comes from.

true, but then again, not áll @ are KoDEx, some are just Kotlin ;P in any case, you'll need the intellij plugin to highlight it correctly, and it'll pickup $ as well :)

Jolanrensen · 2026-01-19T15:14:18Z

docs/KDocs-Guidelines.md

+Some part of public API is not intended for end users, but can be used in Compiler Plugin or potential
+KDF extension libraries. These methods should have a small KDocs as well.
+
+For internal API, please add at least a small note.


or anything you wished was there if someone else wrote the function and you had to use and understand it ;P

Jolanrensen · 2026-01-19T15:15:18Z

docs/KDocs-Guidelines.md

+
+## Kotlin DataFrame Operations KDoc Structure
+
+Operation KDocs size and structure completely depend on the operation complexity. 


Copy, soldier! Operation KDocs is a GO! :D

Jolanrensen · 2026-01-19T15:17:03Z

docs/KDocs-Guidelines.md

+   * For a better understanding of the complex operation, we write an [operation grammar](#grammar) using a 
+   [special notation](https://github.com/Kotlin/dataframe/blob/master/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.
+


operation that are called on columns

Actually, such operations usually are of the first kind.

actually, yes, you're right :)

Jolanrensen · 2026-01-19T15:23:17Z

docs/KDocs-Guidelines.md

+     * {@comment Version of [SelectingColumns] with correctly filled in examples}
+     * @include [SelectingColumns] {@include [Set~OperationName~OperationArg]}
+     */
+    interface ~OperationName~Options


This is gonna be a typealias ~OperationName~Options = Nothing after 2.3.

Jolanrensen · 2026-01-19T15:23:45Z

docs/KDocs-Guidelines.md

+// Set operation in [SelectingColumns] examples (in [SelectingColumns.Dsl] and so on)
+/** {@set [SelectingColumns.OPERATION] [~operationName~][~operation~]} */
+@ExcludeFromSources
+private interface Set~OperationName~OperationArg


this will be a type alias too. It's fine for now like this, but we should change it later :)

Jolanrensen · 2026-01-19T15:24:25Z

docs/KDocs-Guidelines.md

+    // `SelectingColumns` helper KDoc with this operation in examples
+    // - for operations with columns selection
+    /**
+     * {@comment Version of [SelectingColumns] with correctly filled in examples}


unnecessary {}. @comment ends when @include begins

they are only needed when you want to use a tag inline

Jolanrensen · 2026-01-19T15:24:45Z

docs/KDocs-Guidelines.md

+}
+
+// Set operation in [SelectingColumns] examples (in [SelectingColumns.Dsl] and so on)
+/** {@set [SelectingColumns.OPERATION] [~operationName~][~operation~]} */


unnecessary {}

Jolanrensen · 2026-01-19T15:25:05Z

docs/KDocs-Guidelines.md

+
+// Common KDoc part for different overloads of the same method
+/**
+ * {@include [~OperationName~Docs]}


unnecessary {}

AndreiKingsley added 3 commits January 17, 2026 19:03

kdoc guidelines

61788ca

kdoc guidelines helper structure

d2b8e03

kdoc guidelines fixes

6752779

Jolanrensen reviewed Jan 19, 2026

View reviewed changes

AndreiKingsley added 2 commits January 19, 2026 21:52

update KDocs guidelines for clarity and improved references

0669c0d

KDocs guideline add TOC

779106c


		## Kotlin DataFrame Operations KDoc Structure

		Operation KDocs size and structure completely depend on the operation complexity.

Documentation guidelines #1660

Are you sure you want to change the base?

Documentation guidelines #1660

Uh oh!

Conversation

AndreiKingsley commented Jan 19, 2026

Uh oh!

Jolanrensen commented Jan 19, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AndreiKingsley Jan 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AndreiKingsley Jan 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

AndreiKingsley Jan 19, 2026 •

edited

Loading

AndreiKingsley Jan 19, 2026 •

edited

Loading