Добавление параметров для диагностики¶

Некоторые диагностики могут иметь параметры, позволяющие конечным пользователям настраивать алгоритм работы.
В качестве примера, возможным параметром может быть максимальная длина строки для замечания на длинные строки, перечень числовых констант, не являющихся магическими числами.

Реализация параметра диагностики¶

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

Доработка класса диагностики¶

В класс диагностики необходимо добавить константное поле, в котором будет сохранено значение параметра по-умолчанию. Например private static final String DEFAULT_COMMENTS_ANNOTATION = "//@";.

Необходимо добавить приватное поле, в котором будет храниться значение параметра. Поле необходимо аннотировать @DiagnosticParameter и указать тип параметра, значение по умолчанию (значение всегда строкового типа), а также описание параметра.
Например

@DiagnosticParameter(
    type = String.class,
    defaultValue = "" + DEFAULT_COMMENTS_ANNOTATION
  )
  private String commentsAnnotation = DEFAULT_COMMENTS_ANNOTATION;

Если параметр примитивный или типа String и он устанавливается в соответствующее свойство класса диагностики простым сеттером, то на этом все.
Если же параметр более сложный, например строка-паттерн для регулярного выражения, которое необходимо вычислить перед установкой, то нужно реализовать метод установки значений параметров configure.

Например, есть два параметра:

commentAsCode - считать комментарии как код, типа булево
excludeMethods - методы, которые не надо проверять, типа ArrayList

Тогда метод установки значений параметров будет выглядеть:

 @Override
  public void configure(Map<String, Object> configuration) {
    // для установки "простых свойств", включая "commentAsCode"
    super.configure(configuration);

    // установка "сложного" свойства "excludeMethods"
    String excludeMethodsString =
      (String) configuration.getOrDefault("excludeMethods", EXCLUDE_METHODS_DEFAULT);
    this.excludeMethods = new ArrayList<>(Arrays.asList(excludeMethodsString.split(",")));
  }

Доработка тестов¶

Обязательно нужно добавить тест для случая изменения настроек диагностики.
Тест добавляется во все тот же класс теста диагностики (отдельный метод для каждой комбинации вариантов настроек диагностики). В начале теста необходимо выполнить установку значения параметра диагностики, последующие действия аналогичны общим правилам написания тестов.
Для установки параметра диагностики из теста необходимо получить конфигурацию диагностики по-умолчанию, используя метод getDefaultConfiguration() из метаданных текущей диагностики diagnosticInstance.getInfo(). Затем выполнить изменение значения параметра, путем добавления в коллекцию конфигурации, а затем переконфигурировать текущую диагностику, обратившись к методу configure.
Пример

// получение текущей конфигурации диагностики
Map<String, Object> configuration = diagnosticInstance.getInfo().getDefaultConfiguration();

// установка нового значения
configuration.put("commentsAnnotation", "//(с)");

// переконфигурирование
diagnosticInstance.configure(configuration);

Добавление описания параметров¶

Для корректной работы необходимо в ресурсных файлах диагностики добавить для каждого языка описание параметра.
Ресурсы диагностики расположены в файлах resources/com/github/_1c_syntax/bsl/languageserver/diagnostics/<DIAGNOSTIC_KEY>_en.properties и resources/com/github/_1c_syntax/bsl/languageserver/diagnostics/<DIAGNOSTIC_KEY>_ru.properties.
В каждом файле необходимо добавить новую строку с именем параметра и его описанием

commentsAnnotation=Пропускать комментарии-аннотации, начинающиеся с указанных подстрок. Список через запятую. Например: //@,//(c)

Доработка документации¶

Добавление информации о параметрах диагностики в документацию вручную не требуется: добавление происходит автоматически при сборке.