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)*)? ')')?;

    LiteralAnnotationArgument | TypeRefAnnotationArgument



10.1.2. Properties

We use the map notation for retrieving annotation properties and values from a list of annotations, for example x.annotationsRequired, or shorter x@Required.

10.1.3. Element-Specific Annotations

The following annotations are element-specific and are explained in the corresponding sections:

Table 11. Element-Specific Annotations
Annotation Element Types Section


TypeDefiningElement, Member, Function, Export






Class, Member












Class, Export Statement


Script, ExportDeclaration, ExportableElement


External Declaration


External Declaration


TypeDefiningElement, Member












1. intended for internal use only; will be removed

10.1.4. General Annotations 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. 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 errorMessage text. If errorMessage 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.

Example 98. IDEBUG Example

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)
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. Suppress Warnings
This is not part of the current version

10.2. Declaration of Annotations

This is not part of the current version

Quick Links