Define Custom Annotation Format

This example shows how to create and edit an XML file to define an annotation format and map it to the Polyspace^® annotation syntax. Once you create and edit the XML file, pass the file to Polyspace by using option -xml-annotations-description.

To define multiple custom annotation formats, see Define Multiple Custom Annotation Syntaxes.

To get started, copy the following code to a text editor and save it on your machine as annotations_description.xml.

<?xml version="1.0" encoding="UTF-8"?>

<Annotations xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:noNamespaceSchemaLocation="annotations_xml_schema.xsd"
             Group="example XML">
			 
	
 <Expressions Search_For_Keywords="myKeyword"
			  Separator_Result_Name="," >
    <!-- Define annotation format in this
	section by adding <Expression/> elements -->
   
   <Expression Mode="SAME_LINE"
               Regex="myKeyword\s+(\w+(\s*,\s*\w+)*)"
               Rule_Identifier_Position="1"
               />	
	
   <Expression Mode="GOTO_INCREMENT"
               Regex="myKeyword\s+(\+\d+\s)(\w+(\s*,\s*\w+)*)"
               Increment_Position="1"
		  Rule_Identifier_Position="2"     
			   />	
	
  <Expression Mode="BEGIN"
               Regex="myKeyword\s*(\w+(\s*,\s*\w+)*)\s*Block_on"
               Rule_Identifier_Position="1"
		  Case_Insensitive="true"
			   />

   <Expression Mode="END"
               Regex="myKeyword\s*(\w+(\s*,\s*\w+)*)\s*Block_off"
               Rule_Identifier_Position="1"
			   />	
   <Expression Mode="END_ALL"
               Regex="myKeyword\sBlock_off_all"
			   />
	
			
   <Expression Mode="SAME_LINE"
               Regex="myKeywords\s+(\w+(\s*,\s*\w+)*)(\s*\[(\w+\s*)*([:]\s*(\w+\s*)+)*\])*(\s*-*\s*)*([^-]*)(\s*-*)*"
               Rule_Identifier_Position="1"
	         Status_Position="4"
		  Severity_Position="6"
		  Comment_Position="8"

               />	
		
	<!-- SAME_LINE example with more complex regular expression.
		Matches the following annotations:
		//myKeywords 50 [my_status:my_severity] -Additional comment-
		//myKeywords 50 [my_status]
		//myKeywords 50 [:my_severity]
		//myKeywords 50 -Additional comment-
			-->
					
 </Expressions>
 
 <Mapping>
	<!-- Map your annotation syntax to the Polyspace annotation
	syntax by adding <Result_Name_Mapping /> elements in this section -->
    
	<Result_Name_Mapping Rule_Identifier="100" Family="RTE" Result_Name="ZDV"/>
	<Result_Name_Mapping Rule_Identifier="50" Family="MISRA-C3" Result_Name="8.4"/>
	<Result_Name_Mapping Rule_Identifier="51" Family="MISRA-C3" Result_Name="8.7"/>
	<Result_Name_Mapping Rule_Identifier="ALL_MISRA" Family="MISRA-C3" Result_Name="*"/>

 </Mapping>
</Annotations>

The XML file consists of two parts:

<Expressions>...</Expressions> where you define the format of your annotation syntax.
<Mapping>...</Mapping> where you map your syntax to the Polyspace annotation syntax.

After you edit this file, Polyspace can interpret your custom code annotation when you invoke the option -xml-annotations-description.

Define Annotation Syntax Format

To define an annotation syntax in Polyspace, your syntax must follow a pattern that you can represent with a regular expression. See Regular Expressions. It is recommended that you include a keyword in the pattern of your annotation syntax to help identify it. In this example, the keyword is myKeyword. Set the attribute Search_For_Keywords equal to this keyword.

Once you know the pattern of your annotation, you can define it in the XML by adding an <Expression/> element and specifying at least the attributes Mode, Regex, and Rule_Identifier_Position. For instance, the first <Expression/> element in annotations_description.xml defines an annotation with these attributes:

Mode="SAME_LINE". The annotation applies to code on the same line.
Regex="myKeyword\s+(\w+(\s*,\s*\w+)*)". Polyspace uses the regular expression to search for a string that begins with myKeyword, followed by a space \s+. Polyspace then searches for a capturing group (\w+(\s*,\s*\w+)*) that includes an alphanumeric rule identifier \w+ and, optionally, additional comma-separated rule identifiers (\s*,\s*\w+)*.
Rule_Identifier_Position="1". The integer value of this attribute corresponds to the number of opening parentheses preceding the relevant capturing group in the regular expression. In myKeyword\s+(\w+(\s*,\s*\w+)*), one opening parenthesis precedes the capturing group of the rule identifier (\w+(\s*,\s*\w+)*). If you want to match rule identifiers captured by (\s*,\s*\w+), then you set Rule_Identifier_Position="2" because two opening parentheses precede this capturing group.

The list of attributes and their values are listed in this table. The example column refers to the format defined in annotations_description.xml.

Attribute	Use	Value	Example
`Mode`	Required	`SAME_LINE`	Applies only on the same line as the annotation. `code; //myKeyword 100`
		`GOTO_INCREMENT`	Applies on the same line as the annotation and the following n lines: `3. code; // myKeyword +3 ALL_MISRA 4. /comments / 5. 6. code; 7. code;` The preceding annotation applies to lines 3–6 only.
		`BEGIN`	Applies to the same line and all following lines until a corresponding expression with attribute `Mode="END"` or `"END_ALL"`, or until the end of the file. `//myKeyword 50, 51 Block_on Code block 1; ...`
		`END`	Stops the application of a rule identifier declared by a corresponding expression with attribute `Mode="BEGIN"`. `//myKeyword 50, 51 Block_on Code block 1; ... More code; //myKeyword 50 Block_off` Only rule identifier 50 is turned off. Rule identifier 51 still applies.
		`END_ALL`	Stops all rule identifiers declared by an expression with attribute `Mode="BEGIN"`. `//myKeyword 50, 51 Block_on Code block 1; ... More code; //myKeyword Block_off_all` Rule identifiers 50 and 51 are turned off.
`Regex`	Required	Regular expression search string	See Regular Expressions. `Regex="myKeyword\s+(\w+(\s,\s\w+))"` matches these expressions: `// myKeyword 50, 51 / myKeyword ALL_MISRA, 100 */`
`Rule_Identifier_Position`	Required, except when you set `Mode="END_ALL"`	Integer	The integer value of this attribute corresponds to the number of opening parentheses in the regular expression before the relevant search expression. `<Expression Mode="GOTO_INCREMENT" Regex="myKeyword\s+(\+\d+\s)(\w+(\s,\s\w+))" Increment_Position="1" Rule_Identifier_Position="2"/>` The search expression for the rule identifier `\w+(\s,\s\w+)` is after the second opening parenthesis of the regular expression.
`Increment_Position`	Required only when you set `Mode="GOTO_INCREMENT"`	Integer	The integer value of this attribute corresponds to the number of opening parentheses in the regular expression before the relevant search expression. `<Expression Mode="GOTO_INCREMENT" Regex="myKeyword\s+(\+\d+\s)(\w+(\s,\s\w+)*)" Increment_Position="1" Rule_Identifier_Position="2"/>` The search expression for the increment `\+\d+\s` is after the first opening parenthesis of the regular expression.
`Status_Position`	Optional	Integer	See `Increment_Position` example. When you use this attribute, the entry in your annotation is displayed in the Status column on the Results List pane of the user interface.
`Severity_Position`	Optional	Integer	See `Increment_Position` example. When you use this attribute, the entry in your annotation is displayed in the Severity column on the Results List pane of the user interface.
`Comment_Position`	Optional	Integer	See `Increment_Position` example. When you use this attribute, the entry in your annotation is displayed in the Comment column on the Results List pane of the user interface. Your comment is appended to the string `Justified by annotation in source:`
`Case_Insensitive`	Optional	True or false	When you set this attribute to "true", the regular expression is case insensitive, otherwise it is case sensitive. If you do not declare this attribute in your expression, the regular expression is case sensitive. For `Case_Insensitive="true"`, these annotations are equivalent: `//MYKEYWORD ALL_MISRA BLOCK_ON //mykeyword all_misra block_on`

Map Your Annotation to the Polyspace Annotation Syntax

After you define your annotation format, you can map the rule identifiers you are using to their corresponding Polyspace annotation syntax. You can do this mapping by adding an <Result_Name_Mapping/> element and specifying attributes Rule_Identifier, Family, and Result_Name. For instance, if rule identifier 50 corresponds to MISRA C™: 2012 rule 8.4, map it to the Polyspace syntax MISRA-C3:8.4 by using this element:

<Result_Name_Mapping Rule_Identifier="50" Family="MISRA-C3" Result_Name="8.4"/>

The list of attributes and their values are listed in this table. The example column refers to the format defined in annotations_description.xml.

Attribute	Use	Value	Example
`Rule_Identifier`	Required	User defined. Each value must be unique.	See the mapping section of `annotations_description.xml`
`Family`	Required	Corresponds to Polyspace results family. For a list of allowed values, see allowed values.	See the mapping section of `annotations_description.xml`
`Result_Name`	Required	Corresponds to Polyspace result names. For a list of allowed values, see allowed values.	See the mapping section of `annotations_description.xml`

Define Multiple Custom Annotation Syntaxes

To define more than one annotation syntax, in your XML file, specify a comma separated list of keywords associated with each syntax for the Search_For_Keywords attribute.

For example, if you use custom annotations that follow these patterns to annotate violations of MISRA C: 2012 rules:

int func(int p) //customSyntax M123 $ customSyntax M124
{	
    int i;
    int j = 1;

    i = 1024 / (j - p); 
    return i;
}

int func2(void){ //otherCustomSyntax 50
	int x=func(2);
	return x; 
}

Enter the following in the XML file where you define the custom annotation syntax.

<?xml version="1.0" encoding="UTF-8"?>

<Annotations xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:noNamespaceSchemaLocation="annotations_xml_schema.xsd"
             Group="multipleCustomSyntax">
	<!-- Enter comma separated list of keywords -->		 
  <Expressions Search_For_Keywords="customSyntax,otherCustomSyntax"
			  Separator_Result_Name="$" >
			 							
	<!-- This section defines the annotation syntax format -->	  
   <Expression Mode="SAME_LINE"
               Regex="customSyntax\s(\w+(\s*,\s*\w+)*)"
               Rule_Identifier_Position="1"
               />
	<Expression Mode="SAME_LINE"
               Regex="otherCustomSyntax\s(\w+(\s*,\s*\w+)*)"
               Rule_Identifier_Position="1"
               />		   
 </Expressions>
  <!-- This section maps the user annotation to the Polyspace
  annotation syntax -->
 <Mapping>
	<!-- Mapping for customSyntax rules -->
	<Result_Name_Mapping  Rule_Identifier="M123" Family="MISRA-C3" Result_Name="8.7"/>
       <Result_Name_Mapping  Rule_Identifier="M124" Family="MISRA-C3" Result_Name="D4.6"/>
	<!-- Mapping for otherCustomSyntax rules  -->
    <Result_Name_Mapping  Rule_Identifier="50" Family="MISRA-C3" Result_Name="8.4"/>
 </Mapping>
</Annotations>

When you use multiple custom annotations, each rule identifier must be unique. For instance, in the preceding example, you cannot reuse rule identifier M123 with otherCustomSyntax.