The JSON annotation mechanism is a way of marking up user-defined functions and types in JSON format files. The mechanism enables a user to provide the analyzer with additional information about their code. This information helps the analyzer to both find more errors and issue less false positives.
By using separate annotation files, you can resolve the following issues:
If these cases are not relevant to you, and you would like to perform markup directly in the source code, please consult this documentation.
The mechanism currently supports the following languages:
Follow these steps to use the mechanism:
Available features vary by language. After consulting the general documentation, please read the language-specific part as well:
These are the ways to enable an already existing annotation file:
Option N1. Add a special comment to the source code or to the configuration file of diagnostic rules (.pvsconfig):
//V_PVS_ANNOTATIONS, language:%project_language%, path:%path/to/file.json%Use one of the following values instead of the %project_language% placeholder:
Instead of the %path/to/file.json% placeholder, use the path to the annotation file you want to enable. Both absolute and relative paths are supported. Relative paths are expanded relative to the file that contains the comment for enabling the annotation.
OptionN2 (C and C++ analyzer only) Specify the ‑‑annotation-file (-A) special flag when running pvs-studio-analyzer or CompilerCommandsAnalyzer:
pvs-studio-analyzer --annotation-file=%path/to/file.json%Instead of the %path/to/file.json% wildcard character, use the path to the annotation file you want to enable. Both absolute and relative paths are supported. Relative paths are expanded relative to the current working directory (CWD).
Note 1. You can have multiple annotation files enabled. Specify a separate flag or comment for each file.
Note 2. Prior to version 7.33, for C and C++, you could enable annotations using a comment of the following type:
//V_PVS_ANNOTATIONS %path/to/file%In this case, starting from version 7.33, you will get a message about using an outdated syntax and a suggestion to switch to a new one.
To help you understand how to work with the user annotation mechanism, we have prepared a list of examples for the most common scenarios:
You can find more use cases in the language-specific documentation of the mechanism:
A JSON schema with versioning support is created for each available language. These schemas help modern text editors and IDEs validate and suggest hints while editing.
When you create your own annotation file, add the $schema field to it and set the value for the required language. For example, the value for the C and C++ analyzer looks like this:
{
"version": 1,
"$schema": "https://files.pvs-studio.com/media/custom_annotations/v1/cpp-annotations.schema.json",
"annotations": [
{ .... }
]
}
This enables Visual Studio Code to provide hints when creating annotations:
JSON schemas are currently available for annotations in the following languages:
Not all issues can be detected when validating the JSON schema. If an error occurs while working with a file that contains annotations, the analyzer issues the V019 warning. It helps understand what went wrong. For example, the annotation file is missing, a parsing error has occurred, an annotation has been skipped due to errors in it, etc.