Skip to content
C3

Comments & Documentation

C3 uses three 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.

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
 @deprecated
 @mycustom 2
*>
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 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

Nameformat
@param@param [<ref>] <param> [<description>]
@return@return <description>
@return!@return! <fault1>, <fault2>, ..., [<description>]
@deprecated@deprecated [<description>]
@require@require <expr1>, <expr2>, ..., [<description>]
@ensure@ensure <expre1>, <expr2>, ..., [<description>]
@pure@pure

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

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