10. Annotations
10.1. Introduction
Annotations are used to further define meta properties of language elements such as types, variables and functions. These annotations are used by the compiler and validator to prohibit the developer from introducing constructs which are either not allowed or are unnecessary in certain contexts.
Since annotations are to be processed by the compiler and the compilation cannot be extended by third-party users for security reasons, annotations cannot be defined by developers. Instead, the compiler comes with a predefined set of annotations which are summarized here.
10.1.1. Syntax
Annotations are used similarly as in Java (although new annotations cannot be defined by the user). They are formally defined as follows:
Annotation:'@' AnnotationNoAtSign;
ScriptAnnotation returns Annotation: '@@' AnnotationNoAtSign;
AnnotationNoAtSign returns Annotation:
name=AnnotationName (=> '(' (args+=AnnotationArgument (',' args+=AnnotationArgument)*)? ')')?;
AnnotationArgument:
LiteralAnnotationArgument | TypeRefAnnotationArgument
;
LiteralAnnotationArgument:
literal=Literal
;
TypeRefAnnotationArgument:
typeRef=TypeRef
;10.1.2. Properties
We use the map notation for retrieving annotation properties and values from a list of annotations, for example , or shorter .
10.1.3. Element-Specific Annotations
The following annotations are element-specific and are explained in the corresponding sections:
| Annotation | Element Types | Section |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
10.1.4. General Annotations
10.1.4.1. IDEBUG
@IDEBUG is an annotation similar to Java’s @SuppressWarnings.
It changes the severity of an issue from an error to a warning so that code can be compiled regardless of validation errors.
This is to be used for known IDE bugs only.
10.1.5. Syntax
'@IDEBUG' '(' bugID = INT ',' errorMessage=STRING ')'The annotation is defined transitively and repeatable on script, type declaration, function and method level.
10.1.5.1. Semantics
This annotation will cause errors issued in the scope of the annotation (in the defined script, type, or method) to be transformed to warnings if their message text is similar to the text.
If ends with … (three dots as a single character, created by Eclipse to abbreviate messages), then the error’s message text must start with the specified text.
If no matching error is found, the annotation itself will issue an error.
In the following code snippet, two errors are to be transformed to warnings.
export class TestDataBridge with IModuleTest {
@IDEBUG(166, "{function(number):void} is not a subtype of {function(T):void}.") (1)
@IDEBUG(91, "Incorrect number of arguments: expected 1, got 2.") (2)
@Override public run(): void {
var foo = new Foo(),
cb = function(val: number): void {},
db = DataBridge.<number>bind(foo, "bar");
db.add(cb); (3)
Assert.isTrue(called);
}
}| 1 | The annotation transforms the error {function(number):void} is not a subtype of {function(T):void} into a warning with the following text: |
| 2 | This annotation was proposed as a workaround for IDEBUG-91 which has been fixed. No error message is produced and an error will be issued on this line instead: |
| 3 | The first error occurs since there is a bug in the IDE type system (as of writing this example) where type arguments are not correctly bound in the case of function expressions used as callback methods. |
10.1.5.2. Suppress Warnings
| This is not part of the current version |
10.2. Declaration of Annotations
| This is not part of the current version |