Annotations attach additional metainformation to declarations. Annotations must first be declared, so Safe-DS knows the annotation exists and which inputs are expected. Afterwards, annotations can be called, which is the segment that truly attaches metainformation to declarations.
Declaring an Annotation¶
Let's look at a minimal example of an annotation:
This declaration of an annotation has the following syntactic elements:
- The keyword
- The name of the annotation, here
OnlyForExperts. This can be any combination of upper- and lowercase letters, underscores, and numbers, as long as it does not start with a number. However, we suggest to use
UpperCamelCasefor the names of annotations.
For the annotation
OnlyForExperts, no more inputs are required. It is only used to mark declarations. However, say we want to assign a category to a declaration. We could define individual annotations for each category, such as:
However, these annotations are difficult to process since we need to maintain a list of annotations that define such a category. Instead, it is preferable to define a single annotation called
Category and make it configurable by adding parameters (inputs). Parameters must be declared in the header of the annotation, so callers know they are expected to pass them as an argument.
In the following example, we define the complete
Category annotation with a single parameter with name
category and type
As we can see from the
OnlyForExperts example, we can omit the entire parameter list, if the annotation has no parameters. More information about parameters can be found in the linked document.
Calling an Annotation¶
To attach metainformation to a declaration, the annotation must be called on that declaration. We name the annotated declaration the target of the annotation. Possible targets are
- Annotations (yes, annotations can be the target of annotation calls)
- Compilation units (entire files)
- Enum variants
- Global functions / methods
- Type parameters
The valid targets of an annotation can be restricted with the
Target annotation. By default all targets are allowed. Likewise, an annotation can only be called once on the same declaration by default, unless the annotation is marked asRepeatable.
Annotation calls are always located right in front of their target. Exception: In the case of compilations units they are located at the very top of the file. Here is an example that demonstrates how to call the annotation
OnlyForExperts that we defined above on a class:
Here is a breakdown of the syntax:
- The name of the called annotation (here
class VerySpecificMLModel is not part of the annotation call but simply the class declaration that is targeted by the annotation call. Since the annotation
OnlyForExperts does not specify parameters, we also need not pass arguments and can omit the entire argument list.
For an annotation with parameters, such as the
Category annotation that we defined above, we must pass arguments. The same syntax is used for arguments of annotation calls as for normal calls. We can use positional arguments:
Or we can use named arguments:
safeds.lang contains several annotations that are processed by Safe-DS. Refer to the API documentation for more details. Particularly important are the annotations