multik-kdoc

Multik KDoc Documentation

Multik documentation lives at three layers. When documenting public API, always consider all three:

1. KDoc comments on source code
2. Writerside docs in docs/topics/ — the user-facing documentation site
3. Korro code samples in multik-core/src/commonTest/kotlin/samples/docs/ — executable @Test methods linked into the Writerside markdown

Korro samples exist to serve Writerside docs — they aren't needed for every KDoc, only for API elements that have (or should have) corresponding user documentation topics.

Modes of Operation

Targeted Documentation

The user points to a specific file, class, or function.

1. Read the source code. Understand behavior, edge cases, relationships with other API.
2. Write or update KDoc following the style guide below.
3. Search docs/topics/ for references to this API element.
4. If user docs mention it, verify they still match. Update prose and code examples as needed.
5. If the doc topic uses Korro samples, verify and update the sample test files.
6. If no user doc exists for this element, ask the user whether to add a Writerside doc page (with Korro sample) or skip.

Documentation Audit

The user asks to scan a module, package, or file for gaps.

1. Scan all declarations — public, internal, and private.
2. Flag elements with missing KDoc, empty KDoc (/** */), or KDoc that just restates the signature.
3. Skip override functions — project convention is to omit KDoc on overrides.
4. Present a summary: number of elements found, number undocumented, grouped by file.
5. Write KDoc for each, starting with the most visible/important. Public API gets full treatment; internal/private gets concise docs.
6. After writing public API KDoc, check user docs (steps 3-6 from Targeted flow).

KDoc Style Guide

Public API: Concise and Complete

Public KDoc should fit in a single IDE hover popup. This is the primary constraint — be thorough but not verbose.

Structure (in this order):

1. Description — what the element does. First sentence is the Dokka summary, make it count. Don't restate the signature.
2. Example (for functions) — a brief markdown-style code snippet showing typical usage.
3. @property / @param — one per property/parameter. Describe what it represents and valid range.
4. @return — when the return value isn't obvious from the name + type. Especially important for view-vs-copy semantics and shape changes.
5. @throws — document exceptions and the conditions that trigger them. Multik uses require() and check(), so IllegalArgumentException and IllegalStateException are common.
6. @see — link to 1-3 closely related functions for discoverability (e.g., reshape ↔ flatten). Don't overuse.

Example — function with parameters:

/**
 * Appends the given [value] elements to this array, returning a new flattened 1D array.
 *
 * The source array is flattened before appending. The original is not modified.
 *
 * ```
 * val a = mk.ndarray(mk[1, 2, 3])
 * a.append(4, 5) // [1, 2, 3, 4, 5]
 * ```
 *
 * @param value elements to append.
 * @return a new [D1Array] with size `this.size + value.size`.
 * @throws IllegalArgumentException if [value] contains elements incompatible with the array's [DataType].
 * @see [cat] for concatenation along a specific axis.
 */
public fun <T, D : Dimension> MultiArray<T, D>.append(vararg value: T): D1Array<T>

Example — class:

/**
 * Applies batched math operations to a [MutableMultiArray] in-place without allocating new arrays.
 *
 * Use the [math] block to chain operations sequentially:
 * ```
 * mk.math.inplace(array) {
 *     math { sin() }
 * }
 * ```
 *
 * @param T the numeric element type.
 * @param D the dimension type.
 * @param base the mutable array to modify.
 */
public open class InplaceOperation<T : Number, D : Dimension>(base: MutableMultiArray<T, D>)

Internal / Private: Brief and Functional

For internal and private elements, keep KDoc concise — one or two sentences explaining why this exists and what it does. No @param tags unless parameters are non-obvious. No examples.

/** Computes strides from [shape] in row-major (C) order. Last dimension has stride 1. */
internal fun computeStrides(shape: IntArray): IntArray

/** Checks that [index] is within bounds for [axis] of size [size]. Throws [IndexOutOfBoundsException] if not. */
@PublishedApi
internal inline fun checkBounds(value: Boolean, index: Int, axis: Int, size: Int)

General Rules

• Use [ClassName] and [functionName] for cross-references — they enable IDE navigation and Dokka links.
• Document view-vs-copy semantics explicitly. This is the #1 source of user confusion in ndarray libraries.
• For dimension-changing operations, describe the output shape.
• For generic type parameters (T, D), document constraints beyond the type bound only if they exist.
• Skip KDoc on override functions to avoid duplication.

Syncing with Writerside Docs

After writing or updating KDoc on public API, check whether user docs need updating.

Find Related Topics

Search docs/topics/**/*.md for the class/function name. Check docs/mk.tree for the topic hierarchy.

Verify Consistency

If a topic references the element:

• Descriptions must match the KDoc (the code is the source of truth).
• Code examples must reflect current behavior.
• Parameter names and types must be correct in prose.

Update Korro Samples

Korro is a build plugin that keeps code snippets in Writerside markdown in sync with actual Kotlin test code.

How it works: The gradle task korro scans markdown files listed in the korro { docs = ... } block of multik-core/build.gradle.kts. For each <!---FUN name--> ... <!---END--> block, it finds the matching @Test fun name() in sample test files and replaces the markdown code block with code between // SampleStart and // SampleEnd.

Markdown side (docs/topics/):

<!---IMPORT samples.docs.userGuide.CreatingMultidimensionalArrays-->

## Literal Construction

<!---FUN literal_construction-->

```kotlin
val a = mk.ndarray(mk[1, 2, 3])
// [1, 2, 3]

**Kotlin side** (`multik-core/src/commonTest/kotlin/samples/docs/userGuide/`):

```kotlin
package samples.docs.userGuide

import org.jetbrains.kotlinx.multik.api.mk
import org.jetbrains.kotlinx.multik.api.*
import kotlin.test.Test

class CreatingMultidimensionalArrays {
    @Test
    fun literal_construction() {
        // SampleStart
        val a = mk.ndarray(mk[1, 2, 3])
        // [1, 2, 3]
        // SampleEnd
    }
}

Everything between // SampleStart and // SampleEnd is injected into the markdown — including output comments. This is intentional: output comments show users the expected result directly in the documentation.

Output comment conventions:

• Single-line output: inline comment on the same line — a[2] // 3
• Multi-line output: block comment /* ... */ below the expression
• Sometimes println() + output comment to be explicit

Rules:

• <!---FUN name--> must match the test function name exactly.
• <!---IMPORT package.ClassName--> must match the test class FQN.
• Samples must compile and pass — they are @Test methods.
• User guide samples go in samples/docs/userGuide/, API reference in samples/docs/apiDocs/.

When to create/update samples:

• When documenting a public API function that has a Writerside topic with <!---FUN--> blocks.
• When the existing sample code doesn't match updated behavior.
• When adding a new section to a Writerside topic that needs an executable example.

Validate

After updating samples, remind the user to run:

./gradlew :multik-core:jvmTest --tests "samples.docs.*"