kxmeta-author

Writing aimeta annotations

When to use

• Adding / @kind ... blocks above tables or functions in a q codebase that loads aimeta.
• Editing existing annotations.
• Diagnosing why an annotated item is missing from meta.json (the compiler ran clean but the item didn't surface).

The wire model — tag vocabulary, meta.json shape, type-string rules, references[] semantics — lives in reference/agent-guide.md. This skill covers the behaviour of getting annotations correct.

The two mandatory markers

Every annotated item needs these. Without them the parser drops the item from meta.json — no error, no warning.

• @kind data for a table, @kind function for a callable. @kind table is a common mistake — it silently drops because qdoc's preprocessor only recognises function/data/readme/file.
• @name <bindingName> — required on every annotated item. The compiler reads names from @name only, never from qdoc's auto-detection (unreliable for multi-line lambdas). Convention: leaf for top-level (@name trade), fully-qualified for namespaced (@name .gw.vwap).

Syntax rules

• Annotation lines start with / @tag at column 0. Indented / lines are code context, not annotations.
• One tag per line. A blank line, a non-comment line, or a different binding ends the block.
• Free-text fields run to end-of-line (@desc, @param description, @returns description, @example). Repeatable tags: @param, @col, @example, @uses, @tag, @sampleRow — every other tag appears at most once.
• @authorize takes exactly two static tokens: / @authorize <action> <resource>. Use read data.<table> for a direct data-read API and exec analytic for a higher-level analytic API. Do not put expressions or caller-specific values in either token.
• Types use qdoc names inside {...} (symbol, symbol[], float, timestamp), not q's single-char codes. The compiler maps to s/f/p/… when emitting kdbType.
• Annotations sit immediately above the binding. A blank line between the block and the binding breaks the association.