Comments - The Nitrate Programming Language

Categories of Comments

Nitrate source code comments are broken down into two distinct categories:

  1. Informational comments
  2. Documentation comments

Informational Comments

Informational comments help provide more context to human readers about the nearby code. The compiler ignores these tokens, and they have no impact on the translation of source code other than source location information. Informational comments should be used to explain the purpose of a block of complex code, the reasoning behind a decision, the expected behavior of a complex function, or just make fun jokes.

Informational comments can be single-line or multi-line and they look like this:

// This is a single-line informative comment with C-style syntax
# This is a single-line informative comment with python-style syntax
~> This is a single-line informative comment with my own syntax
/* This is a multi-line informative comment with C-style syntax */
/* Nested /* multi-line
  /* comments
*/ */ are fully supported */

Documentation Comments

Documentation comments are used to auto-generate documentation for the module. Documentation comments are used to summarize the purpose, behavior, contract, usage, and edge cases of an item in a format called Doxygen. For more information about Doxygen syntax, read the Doxygen Documentation.

The compiler shall ignore documentation comments.

/// This is a single-line documentation comment
/** This is a multi-line documentation comment */

/**
 * @brief Calculate the nth Fibonacci number
 * @param n The index of the Fibonacci number to calculate
 * @return The nth Fibonacci number
 * @warning This function may overflow for large n
 */
pub fn pure noexcept fib(n: u128): u128 {
  retif n <= 1, ret n;
  ret fib(n - 1) + fib(n - 2);
}

Formal Definition

<shebang_comment> ::= "#" <any_uft8_except_for_line_feed> "\n"
<double_slash_comment> ::= "//" <any_uft8_except_for_line_feed> "\n"
<inline_arrow_comment> ::= "~>" <any_uft8_except_for_line_feed> "\n"
<multiline_comment> ::= "/*" <idk_how_to_do_nesting_in_bnf> "*/"
<comment> ::= <shebang_comment> | <double_slash_comment> | <inline_arrow_comment> | <multiline_comment>