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 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:
- the markup (annotation) of 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 perform markup directly in the source code, please consult this documentation.
The mechanism currently supports the following languages:
- C and C++ (starting with the 7.31 version);
- C# (starting with the 7.33 version);
Follow these steps to use the mechanism:
- create a JSON file;
- write the necessary annotations according to the JSON schemas;
- enable annotation files in the analysis via the way that suits you best.
Available features vary by 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:
- c is for C;
- cpp is for for C++;
- csharp is 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.
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.
How to facilitate 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#)?
You can find more use cases in the language-specific documentation of the mechanism:
JSON schemas
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:
Analyzer warnings
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.
Was this page helpful?
