Оглавление
Механизм пользовательских аннотаций в формате JSON
Механизм JSON аннотаций — это способ разметки пользовательских функций и типов в файлах формата JSON с целью дать анализатору дополнительную информацию о пользовательском коде. Благодаря этой информации анализатор может как находить больше ошибок, так и выдавать меньше ложных срабатываний.
Использование отдельных файлов с аннотациями позволяет решить следующие проблемы:
- разметка (аннотирование) стороннего (third-party) кода, библиотек и компонентов;
- применение разных наборов аннотаций в зависимости от сценариев использования анализатора.
В случае, если данные сценарии для вас не актуальны, и вы хотели бы проводить разметку прямо в исходном коде, то стоит ознакомиться с отдельной документацией.
На данный момент механизм доступен для следующих языков:
- C и С++ (начиная с версии 7.31);
- С# (начиная с версии 7.33);
- Java (начиная с версии 7.38).
Для того, чтобы воспользоваться механизмом, необходимо:
- Создать файл формата JSON;
- Написать необходимые аннотации согласно JSON-схемам;
- Подключить файлы аннотаций при анализе удобным вам способом.
Доступный функционал отличается в зависимости от используемого языка. После ознакомления с общей документацией желательно также ознакомиться с языко-специфичной частью:
Способы подключения файлов с аннотациями
Подключить уже готовый файл аннотаций можно следующими способами:
Способ N1. Добавить специальный комментарий в исходный код или в файл конфигурации диагностических правил (.pvsconfig):
//V_PVS_ANNOTATIONS, language:%язык_проекта%, path:%путь/до/файла.json%Вместо символа подстановки %язык_проекта% предполагается использование одного из следующих значений:
- для С:
с; - для С++:
cpp; - для С#:
csharp.
Вместо символа подстановки %путь/до/файла.json% предполагается путь до подключаемого файла аннотаций. Поддерживаются как абсолютные, так и относительные пути. Относительные пути раскрываются относительно файла, в котором указан комментарий для подключения аннотации.
Способ N2 (только для С, C++ и Java анализаторов). Указать специальный флаг ‑‑annotation-file (-A) при запуске pvs-studio-analyzer, CompilerCommandsAnalyzer или pvs-studio.jar:
pvs-studio-analyzer --annotation-file=%путь/до/файла.json%Вместо символа подстановки %путь/до/файла.json% предполагается путь до подключаемого файла аннотаций. Поддерживаются как абсолютные, так и относительные пути. Относительные пути раскрываются относительно текущей рабочей директории (CWD).
Способ N3 (только для Java анализатора). Автоматическое подключение по расширению файла.
Файлами аннотаций считаются все файлы с разрешением .annotations.json, находящиеся в директории .PVS-Studio в проекте.
Если проект находится в директории project-gradle, то все следующие файлы автоматически подтянутся анализатором как файлы аннотаций:
project-gradle/.PVS-Studio/test.annotations.json
project-gradle/.PVS-Studio/user.annotations.json
project-gradle/.PVS-Studio/sql.annotations.json
Примечание 1. Может быть подключено несколько файлов с аннотациями. Для каждого файла необходимо указать отдельный флаг или комментарий.
Примечание 2. До версии 7.33, для языков С и С++ аннотации можно было подключить с помощью комментария следующего вида:
//V_PVS_ANNOTATIONS %путь/до/файла%Начиная с версии 7.33, в таком случае будет выдаться специальное сообщение об использовании устаревшего синтаксиса и предложение перейти на новый.
Упрощения для комфортной работы с аннотациями
Готовые примеры
Для облегчения знакомства с механизмом пользовательских аннотаций мы подготовили коллекцию примеров для наиболее часто встречающихся сценариев.
- Как проаннотировать свой nullable тип (С++)?
- Как пометить функцию как опасную или устаревшую (С++)?
- Как пометить функцию как источник/приёмник недостоверных данных (C, С++, C#, Java)?
Больше примеров использования можно увидеть в документации механизма для конкретного языка:
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 сможет давать подсказки при составлении аннотаций:
На данный момент JSON-схемы доступны для аннотаций на следующих языках:
Предупреждения анализатора
Далеко не все проблемы можно диагностировать на уровне валидации JSON-схемы. Если при работе с файлом с аннотациями произошла ошибка, то анализатор сгенерирует предупреждение V019. Оно даст подсказку, что пошло не так. Например: файл с аннотациями отсутствует, произошла ошибка при разборе, аннотация пропущена из-за допущенных в ней ошибок и т.д.
Была ли полезна эта страница документации?
