Comments

A comment is text the compiler skips. Rux has two ordinary forms, for notes to the reader, and two documentation forms, which describe the declaration that follows them and feed rux doc, rux lint and editors.

Comment markers inside string and character literals are ordinary characters: "// not a comment" is a string.

Line comments

// starts a comment that runs to the end of the line. It may stand on a line of its own or follow code.

// The everyday kind of comment.
let width = 80; // It can follow code on the same line.

Block comments

/* starts a comment that ends at the matching */. It may span lines, or sit between any two tokens.

/* A block comment
   over several lines. */
PrintLine(/* the message */ "inline");

Block comments nest: each /* inside a block needs its own */. That makes it safe to comment out code that already contains a block comment.

/*
    Temporarily disabled:
    /* PrintLine("nested"); */
    PrintLine("still inside the outer comment");
*/

A block that never closes is error: block comment is not terminated, reported at its opening /*.

Documentation comments

/// and /** … */ are documentation comments. They attach to the declaration that follows them and describe it as Markdown.

/// Returns the larger of two values.
/// @param a the first value
/// @param b the second value
/// @returns whichever of `a` and `b` is greater
func Max(a: int, b: int) -> int {
    return a > b ? a : b;
}

/**
    Returns the smaller of two values.
    @param a the first value
    @param b the second value
    @returns whichever of `a` and `b` is smaller
*/
func Min(a: int, b: int) -> int {
    return a < b ? a : b;
}

/// A point on a plane.
struct Point {
    /// The horizontal coordinate.
    x: int;
    /// The vertical coordinate.
    y: int;
}

The markers are exact. //// and longer runs of slashes are ordinary line comments, and /**/, /***/ or any block opened with more than two stars is an ordinary block comment, so a decorative banner never becomes documentation.

Attachment

A documentation comment attaches to the nearest following declaration when:

• it starts its own line (indentation is allowed);
• no blank line, ordinary comment or other token comes between it and the declaration or the declaration's first attribute.

Documentation attaches to functions, types, constants, modules, fields, enum and variant cases, interface and extension methods, and extern members. Parameters and type parameters are described with tags rather than with comments inside a parameter list.

Inside a function body there is no declaration to document, so a documentation comment there is an error:

error: documentation comment inside a block is not attached to a declaration
help: write an ordinary '//' comment here; '///' documents the declaration that follows it

A documentation comment that is detached elsewhere — trailing code, followed by a blank line, or at the end of a scope — does not stop compilation; rux lint reports it.

Content and summary

The text is Markdown. A line comment loses /// and one following space; a block comment loses its delimiter lines and common indentation. The first sentence — up to the first ., ! or ? followed by whitespace — is the summary that tools show on its own.

Structured tags

Tags form a block after the prose. Each starts a line; a continuation line is indented by two spaces after the marker.

Tags are case-sensitive. A misspelled or misplaced tag, such as @return for @returns, never fails compilation; rux lint reports it. @deprecated is documentation only — the #Warn attribute is what makes the compiler warn at each use.

See also

• Source Files — how the lexer reads a file
• Comment — the lesson on all three everyday forms
• Documentation — writing documentation a package publishes
• rux doc and rux lint — the tools that read documentation comments