Documentation comments

Platform spec node

Documentation comments

Back to Surface syntax ◎ Open in platform map

Spec standingStandard

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

ADRs

No architecture decision records under adr/ for this feature yet. Standard features must publish at least one ADR or keep a ## Decisions summary on the hub.

Articles

• Documentation comments Structured comments attach human-readable contracts to declarations. Tooling must preserve them through formatting and refactors without changing semantics. article Standard Reviewed Thu May 21
• Lexical and syntax Defines tokens, whitespace, and the context-free skeleton that every later phase assumes. The normative grammar and lexical rules live in the Language Spec; this page records platform ownership and ho… article Standard Reviewed Thu May 21

History

0 revisions (git unavailable at build; counts may be empty)

Open full history on GitHub

No commits recorded for this path.

Completeness

OKarea · 2 SpecSection(s) · 0 H2 heading(s)

Section id	Required	Found
scope	yes	yes
features	yes	yes

Full tree: run pnpm verify:platform-spec-layout (writes src/generated/platform-spec-layout-report.json).

Related spec docs

• Area
  Surface syntax

  Parent area

• Domain
  Language meta

  Parent domain hub

• Domain
  Platform specification

  Cross-cutting index

• Domain
  Execution documentation

  Non-normative legacy execution bridge

Normative specification

Scope

Defines how documentation comments attach to declarations and how tools must expose them. Lexical rules for /// are in Lexical and syntax.

Static rules

• A documentation run (DocRun) is one or more consecutive lines starting with /// where the third / is not followed by another /.
• Documentation must attach only to items parsed through ItemWithDocs or parameter/method/variant doc wrappers.
• Leading documentation on an item must appear immediately before the item’s inner declaration (after attributes, if any).

Dynamic semantics (tooling)

• The compiler must preserve doc text in semantic snapshots for LSP hover and generated API docs.
• Doc text is informative for type checking; it must not alter name lookup or contract satisfaction.
• Tools should render DocRun as Markdown-compatible plain text.

Diagnostics

Malformed doc attachment should warn once the doc pipeline is strict; v0.1 may ignore orphan /// outside wrappers.

Conformance

Formatter must not reorder /// runs across distinct items. LSP must return stored doc strings for resolved symbols.

Decisions

• D-LM-DOC-001 — /// only: Block and // comments never form API documentation.
• D-LM-DOC-002 — Non-normative doc: Doc comments cannot introduce new MUST rules.
• D-LM-DOC-003 — @arg on callables only: Parameter tags apply to functions, methods, and contract methods—not record fields.
• D-LM-DOC-004 — Signatures from compiler: api.json types and links are compiler-derived; prose must not invent parallel type strings.

Platform view

Structured comments attach human-readable contracts to declarations. Tooling must preserve them through formatting and refactors without changing semantics.

Relationship to api.json

beskid doc emits api.json schema v4 with compiler-derived signatures and type links for every resolved symbol. Authors do not duplicate type names in JSON: non-primitive types use typeAnnotation.refItemId for navigation; optional /// prose uses @ref(Qualified.Name) for markdown cross-links in docMarkdown and structured summaryMarkdown.

@ref resolution uses the same qualifiedName index as api.json rows (not raw declaration name alone). Packed docs emit registry links of the form /docs/{package}@{version}/api/{qualifiedName} when a publish context is available; cross-package targets use the target row’s declaringPackage when present. See Registry API reference UI.