Skip to main content

Comments

Comments annotate source code for readers and tools.

Line Comments​

Use // for single-line comments.

// Explain a declaration or a block of code.
let retries = 3;

Block Comments​

Use /* ... */ for multi-line comments.

/*
 * Describe a larger piece of code,
 * its intent, or temporary notes.
 */
fn main() {}

Documentation Comments​

Standardized declaration documentation currently uses line comments placed immediately above the declaration. This is the right place to document functions and structs, and it leaves room for future comment-driven features beyond editor display.

Supported forms today:

  • Summary lines written as // ... or /// ...
  • @param <name> - <description> for function parameters
  • @field <name> - <description> for struct fields
  • @return <description> for function return values

Function example:

// Add two numbers.
// @param a - Left operand
// @param b - Right operand
// @return The sum of both operands
fn add(a: i32, b: i32) -> i32 {
    return a + b;
}

Struct example:

// 2D vector.
// @field x - Horizontal component
// @field y - Vertical component
struct Vec2 {
    x: i32,
    y: i32,
}

Tooling Behavior​

Today, the language server consumes this metadata for editor features such as hover and signature help.

Current scope:

  • The comments attach to the declaration immediately below them.
  • The standardized tags above are supported for functions and structs.
  • Block-style /** ... */ comments are not yet standardized for structured tags.