Annotate Code and Hide Known or Acceptable Results

If a Polyspace^® analysis of your code finds known or acceptable defects or coding rule violations, you can suppress the defects or violations in subsequent analyses. Add code annotations indicating that you have reviewed the issues and that you do not intend to fix them.

You can add annotations through menu items in the Polyspace user interface (or IDE plugins) or by typing them directly in your code. For the general workflow of adding annotations:

In the Polyspace desktop user interface, see Address Results in Polyspace User Interface Through Bug Fixes or Justifications.
In the Polyspace Platform user interface, see Address Results in Polyspace User Interface Through Bug Fixes or Justifications.
In the Polyspace Access web interface, see Address Results in Polyspace Access Through Bug Fixes or Justifications (Polyspace Access).
In IDEs using Polyspace as You Code plugins or extensions, see Review Polyspace as You Code Results in IDEs.
In Simulink^® using block-level annotations, see Address Polyspace Results by Annotating Simulink Blocks.

This topic shows the annotation syntax.

Note that you cannot hide the run-time errors detected with Code Prover from your source code even with code annotations. However, like all other results, the review information associated with a run-time error is extracted from the corresponding code annotation and shown with the result.

Code Annotation Syntax

To add comments directly to your source file, use the Polyspace annotation syntax. The syntax is not case sensitive, and has the following format. Both C style comments within /* */ and C++ style comments starting with // are supported.

Annotating Single Line of Code

To annotate a result on the current line of code (including macros), use this syntax:

line of code; /* polyspace Family:Result_name */

For instance:

var++; /* polyspace DEFECT:INT_OVFL */

Annotations begin with the keyword polyspace and must include the Family and Result_name field values.

You can optionally specify a Status, Severity, and Comment field value:

polyspace Family:Result_name [Status:Severity] "Comment"

For instance:

var++; /* polyspace DEFECT:INT_OVFL [Justified:Low] "Overflow taken into account."*/

If you do not specify a status, Polyspace considers the result justified, and assigns the status No action planned to the result.

For further details, see Annotation Syntax Details and Syntax Examples.

Annotating Code Block

To annotate a block of code, use the following syntax. Note that the annotations apply only to the block of code itself and not to bodies of functions called from the block.

Annotation for current line of code and n following lines:
```
line of code; /* polyspace +n Family:Result_name */
```

Annotation for block of code:

/* polyspace-begin Family:Result_name */
{
   block of code
}
/* polyspace-end Family:Result_name */

Optionally, specify a status, severity and comment.

If annotations for results with the same Family and Result_name are nested, the innermost annotation is used.

For example, in this code, the annotation on line 9 is applied instead of the block annotation, but the block annotation is applied to the violation on line 7.

1  /*polyspace-begin MISRA-C:14.9 [To fix:High] */
2  int main(void) 
3  {
4      int x = 1;
5      int y = x / 2;
6  
7      if (y < 0) /* Block annotation is applied to this violation of MISRA-C:14.9*/
8          y++;
9      if (x > y) /*polyspace MISRA-C:14.9 [Justified:Low] */
10         return x;
11     return x;
12 }
13 /*polyspace-end MISRA-C:14.9 [To fix:High] "Block annotation"*/

When you annotate a code block, the annotation applies only to the issues that arise from within the block. For instance, say you have a function call in the annotated block, and the body of the function gives rise to a violation. This violation is not affected by the annotation around the code block where the function is called.

For further details, see Annotation Syntax Details and Syntax Examples.

Justifying Multiple Results in the Same Line of Code

If a line of code contains more than one result, you can justify the results by using this syntax:

If the results belong to the same family, specify comma-separated result names.
```
line of code; /* polyspace Family:Result_1_name,Result_2_name */
```
If the results belong to different families, specify space-separated family names.
```
line of code; /* polyspace Family_1:Result_1_name Family_2:Result_2_name */
```

Optionally, specify a status, severity and comment.

For further details, see Annotation Syntax Details and Syntax Examples.

Note

Polyspace ignores anything that follows text in double quotes when parsing annotations. To apply an additional annotation after text in double quotes, enter the polyspace keyword again. For example:

/* polyspace Family_1:Result_1_name "comment 1" polyspace Family_2:Result_2_name "comment 2"*/

Annotation Syntax Details

To replace the different annotation fields with their allowed values, use the values in this table or see the examples.

Field	Allowed Value
`Family`	Type of analysis result: `DEFECT` (Polyspace Bug Finder™) `RTE`, for run-time checks (Polyspace Code Prover™) `CODE-METRICS`, for function-level code complexity metrics `VARIABLE`, for global variables (Polyspace Code Prover) `MISRA-C` or `MISRA2004` for MISRA C™: 2004 rule violations. These annotations also apply to MISRA C: 2012 violations based on the mapping between the two standards. The mapping allows you to reuse your justifications for the older standard when migrating to the newer one. See Import Justifications from Older Standard to Newer Standard. `MISRA-AC-AGC` for violations of MISRA C:2004 rules applicable to generated code `MISRA-C3` or `MISRA2012` for MISRA C: 2012 rule violations. The annotation works even for the rules applicable to generated code. `MISRA-C-2023` for MISRA C: 2023 rule violations. The annotation works even for the rules applicable to generated code. `CERT-C` for CERT^® C coding standard violations `CERT-CPP` for CERT C++ coding standard violations `ISO-17961` for ISO/IEC TS 17961 coding standard violations `MISRA-CPP` for MISRA™ C++:2008 rule violations `MISRA-CPP-2023` for MISRA C++: 2023 rule violations `AUTOSAR-CPP14` for AUTOSAR C++14 rule violations `JSF` for JSF^®++ rule violations `GUIDELINE` for software complexity guidelines. `CUSTOM` for violations of custom coding rules `StandardID` for violations of user-defined coding standards. Here, `StandardID` is the short name specified in property `runs/taxonomies/properties/id` of the SARIF file that encodes the user-defined coding standard. For an overview of the SARIF file, see Create User-Defined Coding Standard by Using Polyspace Bug Finder Checkers. To specify all analysis results, use the asterisk character `:`. See Syntax Examples.
`Result_name`	For `DEFECT`, use short names of checkers. See Short Names of Bug Finder Defect Groups and Defect Checkers. For `RTE`, use short names of run-time checks. See Short Names of Code Prover Run-Time Checks (Polyspace Code Prover). For `CODE-METRICS`, use short names of code complexity metrics. See Short Names of Code Complexity Metrics. Note that project and file metrics cannot be justified using code annotations. For `VARIABLE`, the only allowed value is the asterisk character " * ". For coding standard violations, specify the rule number or numbers. For user-defined coding standards, specify the guideline ids. Each guideline of a coding standard is encoded by using an entry in the `run/taxonomies/taxa` array of a SARIF file. The id of a guideline is specified in the `id` property the corresponding `taxa` element. For an overview of the SARIF file, see Create User-Defined Coding Standard by Using Polyspace Bug Finder Checkers. For software complexity guidelines, use acronyms for the guidelines. See pages for individual guidelines in Guidelines. To specify all parts of a result name `[MISRA2012:17.]` or all result names in a family `[DEFECT:]`, use the asterisk character. See Syntax Examples.
`Status`	Text to indicate how you intend to address the error in your code. This value populates the Status column in the Results List pane as: `Unreviewed` `To investigate` `To fix` `Justified` `No action planned` `Not a defect` `Other` Polyspace suppresses results annotated with status `Justified`, `No action planned`, or `Not a defect` in subsequent analyses. If you specify a status that is not an allowed value, Polyspace stores it as a custom status.
`Severity`	Text to indicate how critical you consider the error in your code. This value populates the Severity column in the Results List pane as: `Unset` `High` `Medium` `Low` If you specify a severity that is not an allowed value, Polyspace appends it to the status field and stores it as a custom status. For example, `[To investigate:sporadic]` is displayed in the Status column of the Results List pane as `To investigate sporadic`.
`Comment`	Additional text, such as a keyword or an explanation for the status and severity. This value populates the Comment column in the Results List pane. The additional text can span more than one line in the code. When showing this text in reports, leading and trailing spaces on a line are merged into one space so that the entire text can be read as a single paragraph.

Syntax Examples

Suppress a Single Defect

Enter an annotation on the same line as the defect and specify the Family (DEFECT) and the Result_name (INT_OVFL). When you do not specify a status, Polyspace assigns the status No action planned, and then suppresses the result in subsequent analyses.

int var = INT_MAX;
var++; /* polyspace DEFECT:INT_OVFL */

Suppress a Single Coding Standard Violation

Justify a coding standard violation, for instance, a CERT-C violation.

Enter an annotation on the same line as the violation and specify the Family (CERT-C) and the Result_name (the rule number, for instance, STR31-C). Assign the status Justified, severity Low and a comment.

line of code; /* polyspace CERT-C:STR31-C [Justified:Low] "Overflow cannot happen
                                            because of external constraints." */

Suppress All MISRA C: 2012 Violations Over Multiple Lines

Enter an annotation with +n between polyspace and the Family:Result_name entries. The annotation applies to the same line and the n following lines.

This annotation applies to lines 4–7. The line count includes code, comments, and blank lines.

4. line of code ; // polyspace +3 MISRA2012:* 
5. //comment
6. 
7. line of code;
8. line of code;

Suppress All Code Metrics on Function

To annotate function-level code complexity metrics, in the function definition, enter an annotation on the same line as the function name.

This annotation suppresses all code complexity metrics for function func:

char func(char param) { //polyspace CODE-METRICS:*
   ...
}

Specify Multiple Families in the Same Annotation

Enter each family separated by a space. This annotation applies to all MISRA C:2012 rules 17 and to all run-time checks.

line of code; /* polyspace MISRA2012:17.* RTE:* */

Specify Multiple Result Names in the Same Annotation

After you specify the Family (DEFECT), enter each Result_name separated by a comma.

system("rm ~/.config"); /* polyspace DEFECT:UNSAFE_SYSTEM_CALL,RETURN_NOT_CHECKED */

Suppress Result Showing Global Variable Usage

To justify a Code Prover result showing global variable usage, for instance, an unused global variable, enter the annotation next to the variable declaration.

For instance, to suppress a global variable result with a Justified status, Low severity and some comments, you can enter an annotation like this:

int var; /* polyspace VARIABLE:* [Justified: Low] "Storage repo for later use"*/

Add Explanatory Comments to Annotation

After you specify a Family and a Result_name, you can add a Comment with additional information for your justification. You can provide a comment for all families and result names, or a comment for each family or result name.

Same comment for all results:


line of code; /* polyspace DEFECT:BAD_FREE MISRA2004:* "Comment for defect and MISRA" */

Different comments for different results:
```
line of code; /* polyspace DEFECT:* "Defect comment" polyspace MISRA2004:5.2 "MISRA comment" */
```
When parsing annotations, Polyspace ignores anything after text in double quotes. Enter the polyspace keyword after text in double quote to annotate additional results in the same line of code.

Set Status and Severity

You can specify allowed values or enter custom values for status and severity. A custom severity entry is appended to the status and stored as a custom Status in the user interface.

//Set Status only
line of code; /* polyspace DEFECT:* [To fix] "some comment" */

//Set Status 'To fix' and Severity 'High'
line of code; /* polyspace VARIABLE:* [To fix: High] "some comment"*/

//Set custom status 'Assigned' and Severity 'Medium'
line of code; /* polyspace MISRA2012:12.* [Assigned: Medium] */

Justify Violations in a Code Block

Use annotation to justify violations arising from a block of code. For instance, consider this code:

double foo(void){
	constexpr int speedLimit = 65;
	constexpr double coeff = 0.2;
	int flag{0};
	int negOne{-1};
	//... 
	return (flag)?speedLimit*coeff*negOne
	: speedLimit*coeff*negOne - 35; //Noncompliant
}

int main(){
	
	/* polyspace-begin AUTOSAR-CPP14:A5-1-1 [Justified: Low]"Known Constant"*/
	//....
	for(int i = 0; i<10;++i){
		foo();
		//...
	}
	
	/* polyspace-end AUTOSAR-CPP14:A5-1-1  [Justified: Low]"Known Constant"*/
	return 1;
}

The for loop has hard coded literal as the loop boundary, which is a violation of

AUTOSAR
                        C++14 Rule A5-1-1

. By annotating the block with the syntax /*polyspace begin...*/ {...}/*polyspace-end...*/, the violation in the line for(int i = 0; i<10;++i){ appears as a justified defect in the results list.

The annotated block contains a call to the function foo(). The annotations do not apply to the body of this function. For instance, the violation in the return statement of foo() appears as an unreviewed defect.

Annotate Results in Spliced Lines

Annotate results that appear in a spliced line of code. Consider this code:

#include <stdio.h>

#define NULL_PTR ((void*)0)

extern  int *value; 
extern int *ptr[10];
void callfoo(int **);

void t1(int val) {
  callfoo(&value);
    /* polyspace +1 RTE:OVFL */
    printf("Dereferenced value: %d %d %d %d\n", NULL_PTR, *ptr[val], *value+val, \
  val);
}

The runtime check Overflow (Polyspace Code Prover) in the spliced line is suppressed in subsequent reviews.

Code Annotation Warnings

If you enter a code annotation incorrectly or the annotation no longer applies, the analysis log contains a warning:

Warning: These Polyspace annotations do not apply to the current code

The warning can mean one of the following:

The issue is no longer detected because of code fixes or changes in analysis configuration.
For instance, an annotation such as:
```
/* polyspace RTE:IDP [No action planned:Low] */
```
Might no longer apply because the Illegally dereferenced pointer check (annotated as IDP), which was previously red or orange, is now green.
The annotation syntax is incorrect.
An annotation beginning with polyspace followed by a word and then a : (colon) such as:
```
// polyspace Family: 
```
is considered as a Polyspace annotation justifying a result. If the word Family following polyspace is not a type of Polyspace result such as DEFECT or RTE, the analysis considers the annotation as invalid and shows the warning. For instance, this annotation triggers the warning:
```
// polyspace TODO: Fix in March dev cycle
```
since TODO is not a type of Polyspace result. To avoid these warnings, use another separator, for instance, instead of a colon. For the full list of result types, see Code Annotation Syntax.

Ignoring Code Annotations

In some cases, you might want to run a clean analysis as if the results have not been previously reviewed. For instance, you might want to perform a worst-case analysis where you see all previously justified results.

You can use the option -ignore-code-annotations to run such an analysis with no history. The analysis ignores the code annotations and shows all annotated results without any review information taken from the annotations.