Comments

C3 has four distinct comment types:

1. The normal // single line comment.
2. The classic /* ... */ multi-line C style comment, but unlike in C they are allowed to nest.
3. Documentation comments <* ... *> the text within these comments will be parsed as documentation and optional Contracts on the following code.
4. Shebang comment #!, which works like a single line comment, but is only valid as the first two characters in a file.

Doc contracts¶

Documentation contracts start with <* and must be terminated using *>. Any initial text up until the first @-directive on a new line will be interpreted as free text documentation.

For example:

<*
 Here are some docs.
 @param num_foo : `The number of foos.`
 @require num_foo > 4
 @require num_foo <= 100 : "Prevent too many foos."
 @deprecated
 @mycustom "2"
*>
fn void bar(int num_foo)
{
    io::printfn("%d", num_foo);
}

Doc Contracts Are Parsed¶

The following was extracted:

• The function description: "Here are some docs."
• The num_foo parameter has the description: "The number of foos".
• A Contract annotation for the compiler: @require num_foo > 4 which tells the compiler and a user of the function that a precondition is that num_foo must be greater than 4.
• A second contract annotation with the description: "Prevent too many foos".
• A function Attribute marking it as @deprecated, which displays warnings.
• A custom function Attribute @mycustom. The compiler is free to silently ignore custom Attributes, they can be used to optionally emit warnings, but are otherwise ignored.

Available annotations¶

See Contracts for information regarding @require, @ensure, @return?, @const, @pure.