TestAnnotation

public struct TestAnnotation : Hashable

A test annotation in a source file.

Test annotations are parsed from comments in the source. They are composed of a command with, optionally, an argument and/or line offset.

//! <offset> <command> <argument>

The character sequence //! is recognized as an annotation line opener, unless it is already part of a comment. The characters between //! and the next new line form an annotation body. For example:

//! @+1 line-annotation a b c
foo()

The line offset of the annotation is +1, its command is line-annotation and its argument is the string “a b c” (without quotes).

The character sequence /*! is recognized as an annotation block opener, unless it is already part of a comment. The block terminates immediately after a matching multiline comment closing delimiter (i.e., */). The sequence of characters that starts immediately after an annotation block opener and the corresponding comment closing delimiter form an annotation body.

An annotation body corresponds to a single annotation. When present, the line offset is parsed as a natural number prefixed by either @+ or @-. The next sequence of non-whitespace characters is parsed as the command. Preceding whitespaces are ignored; following whitespaces are ignored only if they are on the same line as the command. The remainder of the annotation body is parsed as the argument.

If the argument starts on a different line than the command, the spaces before the first non-space first non-space character of the argument defines the indentation pattern of the argument and are not part of its value. Each line of an argument must be prefixed by the its indentation pattern.

/*! cpp
struct Foo {
  int bar;
};
*/

The command of the annotation is cpp and the argument is a C++ struct declaration with no indentation on the first and last line, and two spaces before the field declaration..