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¶

Fault inheritance¶

It is possible to reference the faults of another function or macro by using the syntax @return? some_func!. This will include all faults returned by some_func. This can be combined with other faults.

<*
 @return? check_triangle!, io::EOF
*>
fn TriangleKind? get_triangle_kind(Triangle* triangle)
{
    check_triangle(triangle)!;
    // ...
}

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

*[<ref>] is an optional mutability description e.g. [&in] *[<description>] denotes that a description is optional.