# Механизм пользовательских аннотаций в формате JSON Механизм JSON аннотаций — это способ разметки пользовательских функций и типов в файлах формата JSON с целью дать анализатору дополнительную информацию о пользовательском коде\. Благодаря этой информации анализатор может как находить больше ошибок, так и выдавать меньше ложных срабатываний\. Использование отдельных файлов с аннотациями позволяет решить следующие проблемы: * разметка \(аннотирование\) стороннего \(third\-party\) кода, библиотек и компонентов; * применение разных наборов аннотаций в зависимости от сценариев использования анализатора\. В случае, если данные сценарии для вас не актуальны, и вы хотели бы проводить разметку прямо в исходном коде, то стоит ознакомиться с отдельной [документацией](https://pvs-studio.ru/ru/docs/manual/0040/)\. На данный момент механизм доступен для следующих языков: * C и С\+\+ \(начиная с версии 7\.31\); * С\# \(начиная с версии 7\.33\); * Java \(начиная с версии 7\.38\)\. Для того, чтобы воспользоваться механизмом, необходимо: 1. Создать файл формата JSON; 1. Написать необходимые аннотации согласно JSON\-схемам; 1. Подключить файлы аннотаций при анализе удобным вам способом\. Доступный функционал отличается в зависимости от используемого языка\. После ознакомления с общей документацией желательно также ознакомиться с языко\-специфичной частью: * [для C и С\+\+](https://pvs-studio.ru/ru/docs/manual/6743/); * [для С\#](https://pvs-studio.ru/ru/docs/manual/6808/); * [для Java](https://pvs-studio.ru/ru/docs/manual/7180/)\. ## Способы подключения файлов с аннотациями Подключить уже готовый файл аннотаций можно следующими способами: **Способ N1**\. Добавить специальный комментарий в исходный код или в файл конфигурации диагностических правил \(`.pvsconfig`\): ```cpp //V_PVS_ANNOTATIONS, language:%язык_проекта%, path:%путь/до/файла.json% ``` Вместо символа подстановки `%язык_проекта%` предполагается использование одного из следующих значений: * для С: `с`; * для С\+\+: `cpp`; * для С\#: `csharp`\. Вместо символа подстановки `%путь/до/файла.json%` предполагается путь до подключаемого файла аннотаций\. Поддерживаются как абсолютные, так и относительные пути\. Относительные пути раскрываются относительно файла, в котором указан комментарий для подключения аннотации\. **Способ N2** \(только для С, C\+\+ и Java анализаторов\)\. Указать специальный флаг `--annotation-file (-A)` при запуске `pvs-studio-analyzer`, `CompilerCommandsAnalyzer` или `pvs-studio.jar`: Для C и C\+\+: ```cpp pvs-studio-analyzer --annotation-file=%путь/до/файла.json% ``` Для Java: ```cpp java -jar pvs-studio.jar --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, для языков С и С\+\+ аннотации можно было подключить с помощью комментария следующего вида: ```cpp //V_PVS_ANNOTATIONS %путь/до/файла% ``` Начиная с версии 7\.33, в таком случае будет выдаться специальное сообщение об использовании устаревшего синтаксиса и предложение перейти на новый\. ## Упрощения для комфортной работы с аннотациями ### Готовые примеры Для облегчения знакомства с механизмом пользовательских аннотаций мы подготовили коллекцию примеров для наиболее часто встречающихся сценариев\. * Как проаннотировать свой nullable тип \([С\+\+](https://pvs-studio.ru/ru/docs/manual/6743/#ID94FD89D762)\)? * Как пометить функцию как опасную или устаревшую \([С\+\+](https://pvs-studio.ru/ru/docs/manual/6743/#ID5354E87769)\)? * Как пометить функцию как источник/приёмник недостоверных данных \([C](https://pvs-studio.ru/ru/docs/manual/6743/#ID0A535D8A77), [С\+\+](https://pvs-studio.ru/ru/docs/manual/6743/#ID0A535D8A77), [C\#](https://pvs-studio.ru/ru/docs/manual/6808/#method_annotation), Java\)? Больше примеров использования можно увидеть в документации механизма для конкретного языка: * [Все примеры для С\+\+](https://pvs-studio.ru/ru/docs/manual/6743/#examples); * [Все примеры для C\#](https://pvs-studio.ru/ru/docs/manual/6808/#examples)\. ### JSON\-схемы Для каждого доступного языка составлена [JSON\-схема](https://pvs-studio.ru/ru/docs/manual/6743/#ID2BD2DA9D35) с поддержкой версионирования\. Благодаря этим схемам современные текстовые редакторы и 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](https://import.viva64.com/docx/blog/Custom_annotations_JSON_ru/image1.png) На данный момент JSON\-схемы доступны для аннотаций на следующих языках: * [JSON\-схема для С\+\+](https://pvs-studio.ru/ru/docs/manual/6743/#ID2BD2DA9D35); * [JSON\-схема для С\#](https://pvs-studio.ru/ru/docs/manual/6808/#schema); * [JSON\-схема для Java](https://pvs-studio.ru/ru/docs/manual/7180/#schema)\. ### Предупреждения анализатора Далеко не все проблемы можно диагностировать на уровне валидации JSON\-схемы\. Если при работе с файлом с аннотациями произошла ошибка, то анализатор сгенерирует предупреждение [V019](https://pvs-studio.ru/ru/docs/warnings/v019/)\. Оно даст подсказку, что пошло не так\. Например: файл с аннотациями отсутствует, произошла ошибка при разборе, аннотация пропущена из\-за допущенных в ней ошибок и т\.д\. ![Custom_annotations_JSON_ru/image2.png](https://import.viva64.com/docx/blog/Custom_annotations_JSON_ru/image2.png)