Contents
User annotation mechanism in JSON format
The JSON annotation mechanism is a way of marking up user-defined functions and types in JSON format files. The mechanism enables providing the analyzer with additional information about their code, helping the analyzer detect more errors and issue less false positives.
By using separate annotation files, you can resolve the following issues:
- adding annotations to third-party code, libraries, and components;
- using different sets of annotations depending on the scenarios of the analyzer use.
If these cases are not relevant to you, and you would like to mark up directly in the source code, please consult this documentation.
The mechanism currently supports the following languages:
- C and C++ (starting with version 7.31);
- C# (starting with version 7.33);
- Java (starting with version 7.38).
Follow these steps to use the mechanism:
- create a JSON file;
- write the required annotations based on the provided JSON schemas;
- enable the annotation files in the analysis using your preferred method.
Features depend on the programming language. After consulting the general documentation, please read the language-specific part as well:
How to enable annotation files
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:
cis for C;cppis for C++;csharpis for C#.
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.
Option N2 (C, C++, and Java analyzers only) Specify the ‑‑annotation-file (-A) special flag when running pvs-studio-analyzer, CompilerCommandsAnalyzer, or pvs-studio.jar:
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).
Option N3 (Java analyzer only). They can be enabled automatically via the file extension.
Any file with the .annotations.json extension located in the .PVS-Studio directory of a project is considered an annotation file.
If the project is located in the project-gradle directory, then the analyzer will automatically recognize the following files as annotation files:
project-gradle/.PVS-Studio/test.annotations.json
project-gradle/.PVS-Studio/user.annotations.json
project-gradle/.PVS-Studio/sql.annotations.json
Note 1. You can have multiple annotation files enabled. Specify a separate flag or comment for each file.
Note 2. Starting with version 7.33, for C and C++ languages, you can enable annotations using the following comment:
//V_PVS_ANNOTATIONS %path/to/file%In this case, starting with version 7.33, you get a message about using a deprecated syntax and a suggestion to switch to a new one.
How to streamline the annotation workflow
Ready-to-use examples
To help you understand how to work with the user annotation mechanism, we have prepared a list of examples for the most common scenarios:
- How to annotate the nullable type (C++)?
- How to mark a function as dangerous or deprecated (C++)?
- How to mark a function as a source/sink of taint data (C, C++, C#, and Java)?
You can find more use cases in the language-specific documentation of the mechanism:
JSON schemas
The 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 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:
Analyzer warnings
The analyzer may not detect all issues when validating the JSON schema. If an error occurs while processing an annotation file, 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.
Was this page helpful?
