From 9dd78cfebda398c5d2bbd55accd5f32fe169f574 Mon Sep 17 00:00:00 2001 From: Jolan Rensen Date: Mon, 5 Aug 2024 14:25:34 +0200 Subject: [PATCH] adding kdoc preprocessing guide --- KDOC_PREPROCESSING.md | 111 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 110 insertions(+), 1 deletion(-) diff --git a/KDOC_PREPROCESSING.md b/KDOC_PREPROCESSING.md index 170aa8f00e..09dc56245d 100644 --- a/KDOC_PREPROCESSING.md +++ b/KDOC_PREPROCESSING.md @@ -321,6 +321,115 @@ like `@file:ExcludeFromSources`. ## KDoc Preprocessor Conventions in DataFrame +### Common Concepts and Definitions + +Some definitions are used in multiple places in the library. +It's often useful to define them in one place and include them in multiple other places or +to just link to them so users can read more explanation while clicking through KDocs. + +Common definitions and concepts are placed in the [documentation folder](./core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation) + and include things like: + +- [Access APIs](./core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/AccessApi.kt) + - To be linked to + - String API, Column Accessors API etc. +- [Selecting Columns](./core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/SelectingColumns.kt) + - To be included in `select`, `update` etc. like `{@include [SelectingColumns.ColumnNames.WithExample]}` (with args). + - Or to be linked to with `{@include [SelectingColumnsLink]}`. + - By name, by column accessor, by DSL etc. +- [Selecting Rows](./core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/SelectingRows.kt) + - To be included like `{@include [SelectingRows.RowValueCondition.WithExample]}` in `Update.where`, `filter`, etc. + - Explains the concept and provides examples (with args) +- `ExpressionsGivenColumn` / `-DataFrame` / `-Row` / `-RowAndColumn` + - To be included or linked to in functions like `perRowCol`, `asFrame`, etc. + - Explains the concepts of `ColumnExpression`, `DataFrameExpression`, `RowExpression`, etc. +- [`NA`](./core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/NA.kt) / [`NaN`](./core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/NaN.kt) + - To be linked to for more information on the concepts +- [DslGrammar](./core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/DslGrammar.kt) + - To be linked to from each DSL grammar by the link interface + +### Link Interfaces + +As can be seen, interfaces that can be "linked" to, like [`AccessApi`](./core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/AccessApi.kt), are often +accompanied by a `-Link` interface, like +```kt +/** [Access API][AccessApi] */ +internal interface AccessApiLink +``` + +This allows other docs to simply `{@include [AccessApiLink]}` if they want to refer to +Access APIs and it provides a single place of truth for if we ever want to rename this concept. + +In general, docs accompanied by a `-Link` interface are meant to be linked to, while docs without +a `-Link` interface are meant to be included in other docs +(and are often accompanied by [`@ExcludeFromSources`](#excludefromsources-annotation-excluding-code-content-from-sources)). +We can deviate from this convention if it makes sense, of course. + +### Arg Interfaces + +When using `@set` and `@get` / `$`, it's a good practice to use a reference as the key name. +This makes the KDoc more refactor-safe, and it makes it easier to understand which arguments +need to be provided for a certain template. + +A good example of this concept can be found in the +[`AllColumnsSelectionDsl.CommonAllSubsetDocs`](./core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/all.kt) +documentation interface. +This interface provides a template for all overloads of `allBefore`, +`allAfter`, `allFrom`, and `allUpTo` in a single place. + +Nested in the documentation interface, there are several other interfaces that define the expected arguments +of the template. +These interfaces are named `TitleArg`, `FunctionArg`, etc. and commonly have no KDocs itself. +Just a simple comment explaining what the argument is for. + +Other documentation interfaces like `AllAfterDocs` or functions then include `CommonAllSubsetDocs` and set +all the arguments accordingly. + +It's recommended to name argument interfaces `-Arg`, and have them nested in the documentation interface, though, +this has not always been done in the past. + +### URLs + +When linking to external URLs, it's recommended to use +[DocumentationUrls](./core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/DocumentationUrls.kt) and +[Issues](./core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/Issues.kt). + +It's a central place where we can store URLs that can be used in multiple places in the library. Plus it makes +it easier to update the documentation whenever (part of) a URL changes. + +### Utils + +The [`utils.kt`](./core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/utils.kt) file contains +all sorts of helper interfaces for the documentation. +For instance `{@include [LineBreak]}` can insert a line break in the KDoc and the family of `Indent` +documentation interfaces can provide you with different non-breaking-space-based indents. + +### Documenting an Operation + +### Clickable Examples + +### DSL Grammars + ## KDoc -> WriterSide -### `@ExportAsHtml` +There's a special annotation, `@ExportAsHtml`, that allows you to export the content of the KDoc of the annotated +function, interface, or class as HTML. +The MarkDown of the KDoc is rendered to HTML using [JetBrains/markdown](https://github.com/JetBrains/markdown) and, in +the case of DataFrame, put in [./docs/StardustDocs/snippets/kdocs](./docs/StardustDocs/snippets/kdocs). +From there, the HTML can be included in any WriterSide page as an iFrame. +This can be done using our custom `` tag. + +An example of the result can be found in the +[DataFrame documentation](https://kotlin.github.io/dataframe/columnselectors.html#full-dsl-grammar). + +The annotation supports two parameters: `theme`, and `stripReferences`, which both are `true` by default. +When the `theme` argument is `true`, some CSS is added to the HTML output to make it look good in combination with +WriterSide. If the `stripReferences` is `true`, all `[]` references are stripped, +like `[name][fully.qualified.name]` -> `name`. This makes the output a lot more readable since +the references won't be clickable in the HTML output anyway. + +Optionally, the tags `@exportAsHtmlStart` and `@exportAsHtmlEnd` can be used to mark the start and end of the content +to be exported as HTML. +This is useful when you only want to export a part of the KDoc. + +`@ExportAsHtml` can also safely be used in combination with `@ExcludeFromSources`.