Аннотации

Аннотация — специальная синтаксическая конструкция во встроенном языке, которая позволяет добавить в программный код метаданные. Добавленные с помощью аннотации метаданные могут использоваться компилятором/интерпретатором и другими механизмами при работе с исходным кодом. Аннотации могут размещаться на объявлениях структур/исключений/перечислений, констант, свойств, методов, параметров, конструкторов — в зависимости от применимости конкретной аннотации.

В программном коде аннотации отмечаются специальным символом @ и указываются перед аннотируемым объектом:

@ИмяАннотации
объект

например:

@ИменованныеПараметры
метод тест(П1: Число = 22, П2: Число, П3 = 44)
;

В примере выше аннотация @ИменованныеПараметры дает возможность указать, что метод/конструктор можно использовать только с именованной формой параметров. При попытке вызвать такой метод с позиционной формой параметров будет ошибка:

тест(П2 = 22) // ok
тест(0, П2 = 22) // ошибка
тест(0, 22) // ошибка

Аннотации могут иметь параметры. Параметры могут быть как обязательными, так и необязательными (иметь значение по умолчанию).

На типы параметров аннотаций и их значения (выражения инициализации) накладываются следующие ограничения:

• Выражение, которое присваивается в качестве значения параметра, должно быть вычислимо во время компиляции. Выражение является вычислимым на этапе компиляции, если оно удовлетворяет следующим критериям:
  • Литералы (включая литералы коллекций) являются вычислимыми.
  • Обращения к константам модулей являются вычислимыми.
  • Операции над вычислимыми являются вычислимыми, кроме следующих исключений:
    • Вызовы методов и обращения к свойствам.
    • Вызовы конструкторов.
    • Операции сложения значения типа Строка со значением другого типа.
  Если выражение не указано, то в параметр присваивается значение по умолчанию. Если для выбранного параметра аннотации нет значения по умолчанию, то во время компиляции возникает ошибка.
• Дополнительно разрешается использовать аннотации как параметры других аннотаций:

  @Аннотация1(Параметр11 = @Аннотация2(Параметр21 = "ЗначениеПараметра" ))

Синтаксис аннотаций с параметрами

• Именованная форма:

  @Аннотация(Параметр1 = Значение1, ... , ПараметрN = ЗначениеN)

• Позиционная форма: допускается использовать позиционную форму только для первого параметра, если аннотация имеет соответствующий признак.
  • Допустимо:

    @Аннотация(Значение1, Параметр2 = Значение2, ... , ПараметрN = ЗначениеN)

    @Аннотация(Параметр1 = Значение1, ... , ПараметрN = ЗначениеN)

  • Недопустимо:

    @Аннотация(Значение1, Значение2, ...)

    @Аннотация(Параметр1 = Значение1, Значение2, ...)

Типы аннотаций

• @ИменованныеПараметры — запрещает вызывать метод с позиционными аргументами (допускаются только именованные аргументы).
• @Реализация — помечает методы, которые являются реализацией абстрактного метода контракта (подробнее).

• Аннотации ОбластиВидимости — определяют область видимость элемента (подробнее):

  • @Глобально;
  • @Локально.
• Аннотации Проверки — определяют необходимость проверки элемента:
  • @ПроверятьИспользованиеЗначения (подробнее).