## 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 $x.annotations\left[Required\right]$, 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

@Internal

TypeDefiningElement, Member, Function, Export

@Undefined

Variable

@StringBased

Enum

@Final

Class, Member

@Spec

FPar

@Override

Method

@Promisifiable

Function

@Promisify

CallExpression

@This

Function

@N4JS

Class, Export Statement

@IgnoreImplementation

Script, ExportDeclaration, ExportableElement

@Global

External Declaration

@ProvidedByRuntime

External Declaration

@TestAPI

TypeDefiningElement, Member

@Polyfill

Class

@StaticPolyfill

Class

@StaticPolyfillAware

Script

@StaticPolyfillModule

Script

@Transient

Field

[1]

1. intended for internal use only; will be removed

#### 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 $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");
}
 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.