Deviations: Support an attribute like comment syntax

Author: lcartey

cpp/common/src/codingstandards/cpp/deviations/CodeIdentifierDeviation.qll

@@ -5,10 +5,10 @@
  * some range of lines in the file containing the comment based on the annotation. The supported marker annotation
  * formats are:
  *  - `<code-identifier>` - the deviation applies to results on the current line.
- *  - `DEVIATION(<code-identifier>)` - same as above.
- *  - `DEVIATION_NEXT_LINE(<code-identifier>)` - this deviation applies to results on the next line.
- *  - `DEVIATION_BEGIN(<code-identifier>)` - marks the beginning of a range of lines where the deviation applies.
- *  - `DEVIATION_END(<code-identifier>)` - marks the end of a range of lines where the deviation applies.
+ *  - `[[codingstandards::deviation(<code-identifier>)]]` - same as above.
+ *  - `[[codingstandards::deviation_next_line(<code-identifier>)]]` - this deviation applies to results on the next line.
+ *  - `[[codingstandards::deviation_begin(<code-identifier>)]]` - marks the beginning of a range of lines where the deviation applies.
+ *  - `[[codingstandards::deviation_end(<code-identifier>)]]` - marks the end of a range of lines where the deviation applies.
  *
  * The valid `code-identifier`s are specified in deviation records, which also specify the query whose results are
  * suppressed by the deviation.
@@ -53,7 +53,7 @@ private predicate commentMatches(Comment comment, string codeIdentifier) {
 /**
  * A deviation marker in the code.
  */
-abstract class DeviationMarker extends Comment {
+abstract class CommentDeviationMarker extends Comment {
   DeviationRecord record;
 
   /**
@@ -65,45 +65,50 @@ abstract class DeviationMarker extends Comment {
 /**
  * A deviation marker for a deviation that applies to the current line.
  */
-class DeviationEndOfLineMarker extends DeviationMarker {
+class DeviationEndOfLineMarker extends CommentDeviationMarker {
   DeviationEndOfLineMarker() {
-    commentMatches(this, "DEVIATION(" + record.getCodeIdentifier() + ")")
+    commentMatches(this, "[[codingstandards::deviation(" + record.getCodeIdentifier() + ")]]")
   }
 }
 
 /**
  * A deviation marker for a deviation that applies to the next line.
  */
-class DeviationNextLineMarker extends DeviationMarker {
+class DeviationNextLineMarker extends CommentDeviationMarker {
   DeviationNextLineMarker() {
-    commentMatches(this, "DEVIATION_NEXT_LINE(" + record.getCodeIdentifier() + ")")
+    commentMatches(this,
+      "[[codingstandards::deviation_next_line(" + record.getCodeIdentifier() + ")]]")
   }
 }
 
 /**
  * A deviation marker for a deviation that applies to a range of lines
  */
-abstract class DeviationRangeMarker extends DeviationMarker { }
+abstract class CommentDeviationRangeMarker extends CommentDeviationMarker { }
 
 /**
  * A deviation marker for a deviation that begins on this line.
  */
-class DeviationBegin extends DeviationRangeMarker {
-  DeviationBegin() { commentMatches(this, "DEVIATION_BEGIN(" + record.getCodeIdentifier() + ")") }
+class DeviationBegin extends CommentDeviationRangeMarker {
+  DeviationBegin() {
+    commentMatches(this, "[[codingstandards::deviation_begin(" + record.getCodeIdentifier() + ")]]")
+  }
 }
 
 /**
  * A deviation marker for a deviation that ends on this line.
  */
-class DeviationEnd extends DeviationRangeMarker {
-  DeviationEnd() { commentMatches(this, "DEVIATION_END(" + record.getCodeIdentifier() + ")") }
+class DeviationEnd extends CommentDeviationRangeMarker {
+  DeviationEnd() {
+    commentMatches(this, "[[codingstandards::deviation_end(" + record.getCodeIdentifier() + ")]]")
+  }
 }
 
 private predicate hasDeviationCommentFileOrdering(
-  DeviationRecord record, DeviationRangeMarker comment, File file, int index
+  DeviationRecord record, CommentDeviationRangeMarker comment, File file, int index
 ) {
   comment =
-    rank[index](DeviationRangeMarker c |
+    rank[index](CommentDeviationRangeMarker c |
       c.getRecord() = record and
       file = c.getFile()
     |
@@ -115,7 +120,7 @@ private predicate mkBeginStack(DeviationRecord record, File file, BeginStack sta
   // Stack is empty at the start
   index = 0 and
   stack = TEmptyBeginStack() and
-  exists(DeviationRangeMarker marker |
+  exists(CommentDeviationRangeMarker marker |
     marker.getRecord() = record and marker.getLocation().getFile() = file
   )
   or

cpp/common/test/deviations/deviations_basic_test/main.cpp

@@ -13,28 +13,28 @@ int main(int argc, char **argv) {
   long double d1; // NON_COMPLIANT (A0-4-2)
   long double d2; // a-0-4-2-deviation COMPLIANT[DEVIATED]
 
-  long double d3; // DEVIATION(a-0-4-2-deviation) COMPLIANT[DEVIATED]
-
+  long double d3; // [[codingstandards::deviation(a-0-4-2-deviation)]]
+                  // COMPLIANT[DEVIATED]
   long double d4; // NON_COMPLIANT (A0-4-2)
-  // DEVIATION_NEXT_LINE(a-0-4-2-deviation)
+  // [[codingstandards::deviation_next_line(a-0-4-2-deviation)]]
   long double d5; // COMPLIANT[DEVIATED]
   long double d6; // NON_COMPLIANT (A0-4-2)
 
-  // DEVIATION_BEGIN(a-0-4-2-deviation)
+  // [[codingstandards::deviation_begin(a-0-4-2-deviation)]]
   long double d7; // COMPLIANT[DEVIATED]
   getX();         // NON_COMPLIANT (A0-1-2)
   long double d8; // COMPLIANT[DEVIATED]
   getX();         // NON_COMPLIANT (A0-1-2)
   long double d9; // COMPLIANT[DEVIATED]
-  // DEVIATION_END(a-0-4-2-deviation)
+  // [[codingstandards::deviation_end(a-0-4-2-deviation)]]
   long double d10; // NON_COMPLIANT (A0-4-2)
-  // DEVIATION_BEGIN(a-0-4-2-deviation)
+  // [[codingstandards::deviation_begin(a-0-4-2-deviation)]]
   long double d11; // COMPLIANT[DEVIATED]
   getX();          // NON_COMPLIANT (A0-1-2)
   long double d12; // COMPLIANT[DEVIATED]
   getX();          // NON_COMPLIANT (A0-1-2)
   long double d13; // COMPLIANT[DEVIATED]
-  // DEVIATION_END(a-0-4-2-deviation)
+  // [[codingstandards::deviation_end(a-0-4-2-deviation)]]
   long double d14; // NON_COMPLIANT (A0-4-2)
   getX();          // NON_COMPLIANT (A0-1-2)
   return 0;

docs/user_manual.md

@@ -426,8 +426,8 @@ The `process_coding_standards_config.py` has a dependency on the package `pyyaml
 A code identifier specified in a deviation record can be applied to certain results in the code by adding a comment marker consisting of a `code-identifier` with some optional annotations. The supported marker annotation formats are:
 
  - `<code-identifier>` - the deviation applies to results on the current line.
- - `DEVIATION(<code-identifier>)` - the deviation applies to results on the current line.
- - `DEVIATION_NEXT_LINE(<code-identifier>)` - this deviation applies to results on the next line.
+ - `codingstandards::deviation(<code-identifier>)` - the deviation applies to results on the current line.
+ - `codingstandards::deviation_next_line(<code-identifier>)` - this deviation applies to results on the next line.
  - `DEVIATION_BEGIN(<code-identifier>)` - marks the beginning of a range of lines where the deviation applies.
  - `DEVIATION_END(<code-identifier>)` - marks the end of a range of lines where the deviation applies.
 
@@ -438,32 +438,32 @@ Here are some examples, using the deviation record with the `a-0-4-2-deviation`
   long double x2; // a-0-4-2-deviation - COMPLIANT
   long double x3; // COMPLIANT - a-0-4-2-deviation
 
-  long double x4; // DEVIATION(a-0-4-2-deviation) - COMPLIANT
-  long double x5; // COMPLIANT - DEVIATION(a-0-4-2-deviation)
+  long double x4; // [[codingstandards::deviation(a-0-4-2-deviation)]] - COMPLIANT
+  long double x5; // COMPLIANT - [[codingstandards::deviation(a-0-4-2-deviation)]]
 
-  // DEVIATION_NEXT_LINE(a-0-4-2-deviation)
+  // [[codingstandards::deviation_next_line(a-0-4-2-deviation)]]
   long double x6; // COMPLIANT
 
-  // DEVIATION_BEGIN(a-0-4-2-deviation)
+  // [[codingstandards::deviation_begin(a-0-4-2-deviation)]]
   long double x7; // COMPLIANT
-  // DEVIATION_END(a-0-4-2-deviation)
+  // [[codingstandards::deviation_end(a-0-4-2-deviation)]]
 ```
 
-`DEVIATION_END` markers will pair with the closest unmatched `DEVIATION_BEGIN` for the same `code-identifier`. Consider this example:
+`codingstandards::deviation_end` markers will pair with the closest unmatched `codingstandards::deviation_begin` for the same `code-identifier`. Consider this example:
 ```cpp
-1 | // DEVIATION_BEGIN(a-0-4-2-deviation)
+1 | // [[codingstandards::deviation_begin(a-0-4-2-deviation)]]
 2 |
-3 | // DEVIATION_BEGIN(a-0-4-2-deviation)
+3 | // [[codingstandards::deviation_begin(a-0-4-2-deviation)]]
 4 |
-5 | // DEVIATION_END(a-0-4-2-deviation)
+5 | // [[codingstandards::deviation_end(a-0-4-2-deviation)]]
 6 |
-7 | // DEVIATION_END(a-0-4-2-deviation)
+7 | // [[codingstandards::deviation_end(a-0-4-2-deviation)]]
 ```
 Here, Line 1 will pair with Line 7, and Line 3 will pair with Line 8.
 
-A `DEVIATION_END` without a matching `DEVIATION_BEGIN`, or `DEVIATION_BEGIN` without a matching `DEVIATION_END` is invalid and will be ignored.
+A `codingstandards::deviation_end` without a matching `codingstandards::deviation_begin`, or `codingstandards::deviation_begin` without a matching `codingstandards::deviation_end` is invalid and will be ignored.
 
-`DEVIATION_BEGIN` and `DEVIATION_END` markers only apply within a single file. Markers cannot be paired across files, and deviations do not apply to included files.
+`codingstandards::deviation_begin` and `codingstandards::deviation_end` markers only apply within a single file. Markers cannot be paired across files, and deviations do not apply to included files.
 
 ##### Deviation permit