Comments¶
Comments are mostly used to add explanations to the code for future readers — which is often yourself. They can also be used to "comment out" code that you want to keep but that should not be run right now, since comments are ignored by the compiler.
Safe-DS has three types of comments, namely
- line comments, which end at a linebreak,
- block comments, which can cover multiple lines, and
- documentation comments, which are used to specify the documentation for declarations.
Line Comments¶
Line comments stop at the end of a line:
They start with //. There must be no space between the slashes. Everything after the double slashes in the same
line is the text of the comment.
To use line comments to "comment out" code you edit in VS Code, select the code and press Ctrl+/ on your
keyboard. This will add // to the beginning of each selected line. You can also trigger this functionality by
using the Toggle Line Comment command in the command palette. To remove the line comments, select the commented code
and press Ctrl+/ again.
Block Comments¶
Block comments have a start and end delimiter, which allows them to cover multiple lines:
They start with /* and end at the inverted delimiter */. There must be no space between the slash
and the star. Block comments cannot be nested. Everything in between the delimiters is the text of the comment.
To use block comments to "comment out" code you edit in VS Code, select the code and press Ctrl+Shift+/ on your
keyboard. This will surround the selected code with /* and */. You can also trigger this functionality
by using the Toggle Block Comment command in the command palette. To remove the block comment, select the commented
code and press Ctrl+Shift+/ again.
Documentation Comments¶
Documentation comments are special block comments that are used to document declarations1. The documentation is used in various places, e.g. when hovering over a declaration or one of its usage in VS Code. Here is an example:
/**
* This is a documentation comment.
*/
segment sum(a: Int, b: Int) -> sum: Int {
yield sum = a + b;
}
They start with /** and end with */. There must be no spaces inside the delimiters. Documentation
comments cannot be nested. Everything in between the delimiters is the text of the comment, except an optional leading
asterisk in each line, which is ignored. Documentation comments are attached to the declaration that follows them. If
there is no declaration following the documentation comment, it is treated as a normal block comment,
with no special meaning.
Markdown¶
Documentation comments support Markdown to format the text. Here is an example:
/**
* This is a documentation comment with **bold** and *italic* text.
*/
segment sum(a: Int, b: Int) -> sum: Int {
yield sum = a + b;
}
Tags¶
Documentation comments can contain tags to provide structured information.
{@link}¶
{@link} is an inline tag that can be used to link to another declaration. It takes the name of the declaration as
an argument:
/**
* Computes the sum of two {@link Int}s.
*/
segment sum(a: Int, b: Int) -> sum: Int {
yield sum = a + b;
}
@param¶
Use @param to document a parameter of a segment. This tag takes the name of the parameter
and its description as arguments. Since a segment can have multiple parameters, this tag can be used multiple times.
/**
* ...
*
* @param a The first summand.
* @param b The second summand.
*/
segment sum(a: Int, b: Int) -> sum: Int {
yield sum = a + b;
}
@result¶
Use @result to document a result of a segment. This tag takes the name of the result and its
description as arguments. Since a segment can have multiple results, this tag can be used multiple times.
/**
* ...
*
* @result sum The sum of `a` and `b`.
*/
segment sum(a: Int, b: Int) -> sum: Int {
yield sum = a + b;
}
@example¶
Use @example to provide an example of how to use a declaration. This tag takes the example code as an argument.
/**
* ...
*
* @example
* pipeline main {
* val result = sum(1, 2);
* }
*/
segment sum(a: Int, b: Int) -> sum: Int {
yield sum = a + b;
}
Limitation
The example code must not contain any blank lines. Otherwise, only the code up to the first blank line is considered.
@since¶
The @since tag can be used to specify when a declaration was added. It takes the version as argument and should be
used only once.