Skip to content

documentation.md

Latest commit

 

History

History
133 lines (105 loc) · 3.18 KB

documentation.md

File metadata and controls

133 lines (105 loc) · 3.18 KB
Raw

Documentation

Mach source-level documentation uses # comments immediately above declarations. Each docstring is one summary line followed by an optional component block.

Grammar

# <summary>
# ---
# <component>: <description>
# <component>: <description>
  • Summary line. <summary> is a single sentance by convention. Additional information may be added in subsequent paragraphs separated by blank # lines.
  • Separator. # --- is present when one or more component lines follow; absent when the docstring is summary-only.
  • Component lines. Each is # <component>: <description>. One line per element exposed by the declaration.
  • Prose is lowercase except for proper nouns and type names.

Component identifiers

Declaration element Component identifier
Function parameter parameter name
Comptime parameter the $name form
Generic type parameter the [T] form
Return value ret
Record field field name
Union variant variant name

Placement

The docstring is the first thing above the declaration. Backtick decorators follow the docstring, immediately above the decl:

# terminate the program with a message
# ---
# msg: text to emit before terminating
#[symbol("panic")]
pub fun panic(msg: *u8) { ... }

Function

# read the wall-clock time
# ---
# out: pointer to Timespec to populate
# ret: 0 on success, negative errno on failure
pub fun realtime(out: *Timespec) i64 { ... }

Generic and comptime parameters appear in the component block under their syntactic form:

# atomic load through a typed pointer
# ---
# [T]:    element type
# $order: memory ordering constraint
# ptr:    pointer to load from
# ret:    loaded value
pub fun load[T]($order: Order, ptr: *T) T { ... }

Summary-only — no separator, no component block:

# yield the CPU to other threads
pub fun spin_hint() { ... }

Record / union / def

# a 2D Cartesian point with i64 coordinates
# ---
# x: horizontal coordinate
# y: vertical coordinate
pub rec Point { x: i64; y: i64; }

# holds either an integer or a float
# ---
# i: integer interpretation
# f: float interpretation
pub uni Number { i: i64; f: f64; }

# an i64 representing years since birth
pub def Age: i64;

Module

A .mach file begins with a module docstring as the first content in the file — before any use, fwd, or decorator.

# cross-platform OS interface
#
# forwards the portable intersection of all supported targets.
# for platform-specific functionality, import the target module
# directly (e.g. myproj.system.os.linux).

Modules may extend beyond the summary with additional paragraphs separated by blank # lines. Other declaration kinds do not extend beyond the summary and the component block.

Value

# maximum counter value before saturation
pub val MAX: i64 = 100;

# module-local request counter
var calls: i64 = 0;

See also