Lexical

Comments

Line comments, block comments, and the /// doc comment that documents the declaration below it.

since 0.1.0-alpha.1linuxwindowswasm

Description

Leviathan has three kinds of comment.

• A line comment starts with // and runs to the end of the line. It can follow code on the same line.
• A block comment starts with /* and ends at the first */. It can sit inside a line or span several lines.
• A doc comment is a run of lines that each start with ///. It documents the declaration directly below it.

Comments are removed before the program is read, so they never change what a program does. A doc comment is the exception in one respect: it must be attached to a declaration, and the compiler reports an error when it is not.

Comments of every kind

/// A counter that remembers how many times it was bumped.
class Counter {
    int n = 0;

    /// Add one to the count and return the new total.
    ///
    /// @returns The count after the bump.
    int bump() {
        this.n = this.n + 1;
        return this.n;
    }
}

// A line comment is ignored.
/* So is a block comment,
   even one that spans lines. */
Counter c = Counter();
c.bump();
console.writeln(c.bump()); // a comment after code is fine

2

Rules

• A line comment runs from // to the end of the line.
• A block comment ends at the first */. Block comments do not nest: in /* a /* b */ c */ the comment ends after b, and c */ is read as code. A block comment that is never closed is a compile error.
• /// starts a doc comment. It must be the first thing on its line, apart from blanks. A /// written after code, or after a closed /* */, is a compile error; use // for a comment after code.
• Consecutive /// lines form one doc comment. The comment attaches to the declaration that follows its last line.
• The line after a doc comment must begin the declaration. A blank line, a // or /* */ comment, or the end of the file in that position is a compile error, so a doc comment can never be silently dropped.
• A doc comment must precede one of: a namespace, class, interface, struct, enum or enum member, a field, method, constructor, accessor or operator, a function, a global or const, an attribute, a rule or macro, or a namespace-level bind. It is a compile error before anything else: a statement, a local variable, a parameter, a block-scoped bind, a use or uses line, or the end of a file.
• A plain // comment may sit above a doc comment. For a declaration with attributes, put the doc comment above the attributes. Writing doc comments both before and after the attributes of one declaration is an error: a declaration carries at most one doc comment.
• A line that starts with four or more slashes (////) is an ordinary line comment, not a doc comment. Use it for banners and separators.
• A doc comment inside a block comment is just text.
• A doc comment on namespace A::B { ... } documents A::B, the innermost namespace.

Examples

A documented method inside a class. The doc comment starts the line and the declaration follows it directly:

class Greeter {
    /// Build the greeting for a name.
    ///
    /// @param name The person to greet.
    /// @returns The greeting text.
    string greet(string name) => "Hello, ${name}";
}

A doc comment above attributes, with a banner comment that is not a doc comment:

Banner, doc comment and attribute

//// ------------------------------
//// Tags
//// ------------------------------

attribute Tag { string label = ""; }

// This plain comment may sit above the doc comment.
/// A class carrying an attribute.
@Tag("demo")
class Thing {
    int size = 3;
}

Thing t = Thing();
console.writeln(t.size);

3

These are all compile errors:

/// a blank line ends the doc comment

class A {}

/// a comment between the doc comment and the declaration
// ends it too
class B {}

/// a doc comment before a statement
console.writeln("hi");

int x = 1; /// a doc comment after code

Notes

Doc comments are the source of the library reference. A doc comment may use Markdown, and lines that start with @param, @returns, @throws, @example, @see, @internal, @deprecated or @platforms are read as tags. A prose line that must start with a literal @ is written \@.

Inside a backtick-delimited rule or macro template, a doc comment must start on the line after the opening backtick and may not contain a backtick.