adding kdoc preprocessing guide

KDOC_PREPROCESSING.md

@@ -321,6 +321,102 @@ 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.
+
+Other documentation interfaces like `AllAfterDocs` 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
+
+### Utils
+
+### 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 `<dataFrame src=""/>` 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]` -> `<code>name</code>`. 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`.