Docstrings and introspection

Kata’s library API is built from the language’s own declarations and docstrings. A signature comes from the parser; its explanation stays beside the code that implements it.

Try the inspector

## introduces a documentation comment. Put a consecutive block directly above a declaration, with no blank line between the block and its declaration. Ordinary # comments remain ordinary comments. Use ##! at the start of a file for module documentation.

KataScript source## Double an integer. ## The original value is unchanged. func double(value: Int): Int { ret value * 2 } print(double(21))

Inspect docstringsReady to inspect.

Change the function’s name, type, or docstring, then inspect it to see what the compiler extracts.

Inspection reads declarations and comments. It does not run the program.

This uses the same Rust inspection API as the command line and generated reference. Strings containing ## are strings, and inspecting a program does not execute it. Running or debugging a program still works normally with its docstrings present.

Inspect a file

kata doc example.ks --json

The versioned JSON describes declarations, parameters, return annotations, members, docstrings, and source locations. Byte spans are UTF-8 offsets; line numbers start at one. Missing type annotations remain unspecified rather than being guessed.

Without a filename, Kata exports its embedded standard library and registered native functions:

kata doc --json

The downloadable JSON index is the export used for this site’s reference. Native functions carry documentation metadata alongside their registrations; declarations implemented in KataScript come from the actual parsed standard-library sources.

Check examples in docstrings

Include a fenced ks program followed by an output fence with its expected standard output. Every example starts with a fresh interpreter and the standard prelude. When checking a file, Kata evaluates that file as setup before each example, so an example can call the function it documents. Setup output is excluded from the comparison.

## A value that may be absent.
##
## ```ks
## print(Opt[Int].Non.unwrap_or(7))
## ```
## ```output
## 7
## ```
enum Opt[T] {
    Val(T),
    Non,
}

Run the standard library’s examples, or check a specific file:

kata doc --check
kata doc example.ks --check

A parse error, failed example, or output mismatch makes the check fail. The runnable examples in Opt, Res, Arr, and Map are authored this way.

Regenerate the website reference

From the repository’s site directory:

npm run docs:generate
npm run docs:reference-check
npm run docs:check

Generation builds the CLI, exports the reference, checks docstring examples, and renders the API pages. Edit the original docstrings instead of the generated Markdown. The site’s verification checks source fingerprints and generated files, so a changed declaration cannot silently ship with an old reference.

The Book remains curated. It uses the same runnable-code controls, while its chapter order, explanations, and exercises are written for learning.