Language Spec Conventions
This document defines conventions used across docs/language/. It exists to
keep the language specification consistent and easy to navigate for both:
- first-time readers learning Silk, and
- returning readers looking up precise rules.
See also: start for recommended reading paths.
Document Structure (Recommended)#
Concept documents should be structured so readers can answer, quickly:
- “What is this feature for?”
- “What syntax does the compiler accept?”
- “What are the rules and edge cases?”
- “What works in the compiler?”
Recommended sections:
- One-paragraph summary
- Supported forms and constraints
- Surface syntax
- Semantics (evaluation order, scoping, control-flow behavior)
- Type checking rules (static requirements and diagnostics)
- Examples
- minimal examples (smallest correct usage)
- realistic examples (how the feature is used in real code)
- Common pitfalls
- Related documents
- Relevant tests (links to
tests/silk/pass_*.slkandtests/silk/fail_*.slk)
Not every concept needs every section, but the goal is that a reader should never have to infer critical rules from examples.
Describe behavior directly#
State accepted syntax, semantics, target constraints, and diagnostics in the present tense. Explain a rejected form precisely rather than describing a development phase. Keep examples runnable, and label intentionally invalid code with its expected diagnostic.
Examples#
Examples in language docs should follow these rules:
-
Use 2-space indentation and spaces only.
-
Prefer complete, runnable snippets when possible:
fn main () -> int { return 0; } -
When an example requires multiple files, label them with comments, e.g.:
// app/main.slk package app; -
When an example is intentionally invalid (to show a rule), label it and mention the expected diagnostic.
Terminology#
These terms are used consistently across the spec:
- Expression: a construct that produces a value and has a type.
- Statement: a construct evaluated for its effects and sequencing.
- Block:
{ stmt* }, a scope boundary and the unit of structured control flow. (Whether blocks are also expressions depends on the concept; docs must be explicit.) - Supported form: syntax accepted for the documented target and context.
Cross-References#
When describing a rule, link to the most relevant concept doc rather than restating it everywhere. Common cross-links include:
- grammar for the exact accepted syntax,
- types for type-system rules and special cases,
- mutability for
mutand borrowing rules, - diagnostics for error codes,
- targets and capabilities for target-specific behavior.
Source repository · Edit this page · View Markdown