Мы используем куки, чтобы пользоваться сайтом было удобно.
Хорошо
to the top
close form

Заполните форму в два простых шага ниже:

Ваши контактные данные:

Шаг 1
Поздравляем! У вас есть промокод!

Тип желаемой лицензии:

Шаг 2
Team license
Enterprise license
** Нажимая на кнопку, вы даете согласие на обработку
своих персональных данных. См. Политику конфиденциальности
close form
Запросите информацию о ценах
Новая лицензия
Продление лицензии
--Выберите валюту--
USD
EUR
RUB
* Нажимая на кнопку, вы даете согласие на обработку
своих персональных данных. См. Политику конфиденциальности

close form
Бесплатная лицензия PVS‑Studio для специалистов Microsoft MVP
* Нажимая на кнопку, вы даете согласие на обработку
своих персональных данных. См. Политику конфиденциальности

close form
Для получения лицензии для вашего открытого
проекта заполните, пожалуйста, эту форму
* Нажимая на кнопку, вы даете согласие на обработку
своих персональных данных. См. Политику конфиденциальности

close form
Мне интересно попробовать плагин на:
* Нажимая на кнопку, вы даете согласие на обработку
своих персональных данных. См. Политику конфиденциальности

close form
check circle
Ваше сообщение отправлено.

Мы ответим вам на


Если вы так и не получили ответ, пожалуйста, проверьте, отфильтровано ли письмо в одну из следующих стандартных папок:

  • Промоакции
  • Оповещения
  • Спам

>
>
Механизм пользовательских аннотаций в ф…
menu mobile close menu
Проверка проектов
Сообщения PVS-Studio
Диагностики общего назначения (General Analysis, C++)
Диагностики общего назначения (General Analysis, C#)
Диагностики общего назначения (General Analysis, Java)
Микрооптимизации (C++)
Диагностика 64-битных ошибок (Viva64, C++)
Реализовано по запросам пользователей (C++)
Cтандарт MISRA
Стандарт AUTOSAR
Стандарт OWASP (C#)
Проблемы при работе анализатора кода
Дополнительная информация
toggle menu Оглавление

Механизм пользовательских аннотаций в формате JSON

02 Окт 2024

Механизм JSON аннотаций — это способ разметки пользовательских функций и типов в файлах формата JSON с целью дать анализатору дополнительную информацию о пользовательском коде. Благодаря этой информации анализатор может как находить больше ошибок, так и выдавать меньше ложных срабатываний.

Использование отдельных файлов с аннотациями позволяет решить следующие проблемы:

  • разметка (аннотирование) стороннего (third-party) кода, библиотек и компонентов;
  • применение разных наборов аннотаций в зависимости от сценариев использования анализатора.

В случае, если данные сценарии для вас не актуальны, и вы хотели бы проводить разметку прямо в исходном коде, то стоит ознакомиться с отдельной документацией.

На данный момент механизм доступен для следующих языков:

  • C и С++ (начиная с версии 7.31);
  • С# (начиная с версии 7.33).

Для того, чтобы воспользоваться механизмом, необходимо:

  • Создать файл формата JSON;
  • Написать необходимые аннотации согласно JSON-схемам;
  • Подключить файлы аннотаций при анализе удобным вам способом.

Доступный функционал отличается в зависимости от используемого языка. После ознакомления с общей документацией желательно также ознакомиться с языко-специфичной частью:

Способы подключения файлов с аннотациями

Подключить уже готовый файл аннотаций можно следующими способами:

Способ N1. Добавить специальный комментарий в исходный код или в файл конфигурации диагностических правил (.pvsconfig):

//V_PVS_ANNOTATIONS, language:%язык_проекта%, path:%путь/до/файла.json%

Вместо символа подстановки %язык_проекта% предполагается использование одного из следующих значений:

  • для С — с;
  • для С++ — cpp;
  • для С# — csharp.

Вместо символа подстановки %путь/до/файла.json% предполагается путь до подключаемого файла аннотаций. Поддерживаются как абсолютные, так и относительные пути. Относительные пути раскрываются относительно файла, в котором указан комментарий для подключения аннотации.

Способ N2 (только для С и C++ анализатора). Указать специальный флаг ‑‑annotation-file (-A) при запуске pvs-studio-analyzer или CompilerCommandsAnalyzer:

pvs-studio-analyzer --annotation-file=%путь/до/файла.json%

Вместо символа подстановки %путь/до/файла.json% предполагается путь до подключаемого файла аннотаций. Поддерживаются как абсолютные, так и относительные пути. Относительные пути раскрываются относительно текущей рабочей директории (CWD).

Примечание 1. Может быть подключено несколько файлов с аннотациями. Для каждого файла необходимо указать отдельный флаг или комментарий.

Примечание 2. До версии 7.33, для языков С и С++ аннотации можно было подключить с помощью комментария следующего вида:

//V_PVS_ANNOTATIONS %путь/до/файла%

Начиная с версии 7.33, в таком случае будет выдаться специальное сообщение об использовании устаревшего синтаксиса и предложение перейти на новый.

Упрощения для комфортной работы с аннотациями

Готовые примеры

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

  • Как проаннотировать свой nullable тип (С++)?
  • Как пометить функцию как опасную или устаревшую (С++)?
  • Как пометить функцию как источник/приёмник недостоверных данных (C, С++, C#)?

Больше примеров использования можно увидеть в документации механизма для конкретного языка:

JSON-схемы

Для каждого доступного языка составлена JSON-схема с поддержкой версионирования. Благодаря этим схемам современные текстовые редакторы и IDE могут проводить валидацию, а также показывать подсказки прямо во время редактирования.

Для этого при составлении собственного файла аннотаций необходимо добавить в него поле $schema, в котором следует указать схему для необходимого языка. Например, для C и С++ анализатора поле будет выглядеть так:

{

    "version": 1,

    "$schema": "https://files.pvs-studio.com/media/custom_annotations/v1/cpp-annotations.schema.json",

    "annotations": [

        { .... }

    ]

}

Например, так Visual Studio Code сможет давать подсказки при составлении аннотаций:

Custom_annotations_JSON_ru/image1.png

На данный момент JSON-схемы доступны для аннотаций на следующих языках:

Предупреждения анализатора

Далеко не все проблемы можно диагностировать на уровне валидации JSON-схемы. Если при работе с файлом с аннотациями произошла ошибка, то анализатор сгенерирует предупреждение V019. Оно даст подсказку, что пошло не так. Например: файл с аннотациями отсутствует, произошла ошибка при разборе, аннотация пропущена из-за допущенных в ней ошибок и т.д.

Custom_annotations_JSON_ru/image2.png