Merge pull request github#4057 from geoffw0/sal

C++: SAL.qll QLDoc and cleanup

Author: rdmarsh2

cpp/ql/src/Microsoft/SAL.qll

@@ -1,5 +1,13 @@
+/**
+ * Provides classes for identifying and reasoning about Microsoft source code
+ * annotation language (SAL) macros.
+ */
+
 import cpp
 
+/**
+ * A SAL macro defined in `sal.h` or a similar header file.
+ */
 class SALMacro extends Macro {
   SALMacro() {
     exists(string filename | filename = this.getFile().getBaseName() |
@@ -20,27 +28,34 @@ class SALMacro extends Macro {
 }
 
 pragma[noinline]
-predicate isTopLevelMacroAccess(MacroAccess ma) { not exists(ma.getParentInvocation()) }
+private predicate isTopLevelMacroAccess(MacroAccess ma) { not exists(ma.getParentInvocation()) }
 
+/**
+ * An invocation of a SAL macro (excluding invocations inside other macros).
+ */
 class SALAnnotation extends MacroInvocation {
   SALAnnotation() {
     this.getMacro() instanceof SALMacro and
     isTopLevelMacroAccess(this)
   }
 
-  /** Returns the `Declaration` annotated by `this`. */
+  /** Gets the `Declaration` annotated by `this`. */
   Declaration getDeclaration() {
     annotatesAt(this, result.getADeclarationEntry(), _, _) and
     not result instanceof Type // exclude typedefs
   }
 
-  /** Returns the `DeclarationEntry` annotated by `this`. */
+  /** Gets the `DeclarationEntry` annotated by `this`. */
   DeclarationEntry getDeclarationEntry() {
     annotatesAt(this, result, _, _) and
     not result instanceof TypeDeclarationEntry // exclude typedefs
   }
 }
 
+/**
+ * A SAL macro indicating that the return value of a function should always be
+ * checked.
+ */
 class SALCheckReturn extends SALAnnotation {
   SALCheckReturn() {
     exists(SALMacro m | m = this.getMacro() |
@@ -50,6 +65,10 @@ class SALCheckReturn extends SALAnnotation {
   }
 }
 
+/**
+ * A SAL macro indicating that a pointer variable or return value should not be
+ * `NULL`.
+ */
 class SALNotNull extends SALAnnotation {
   SALNotNull() {
     exists(SALMacro m | m = this.getMacro() |
@@ -69,6 +88,9 @@ class SALNotNull extends SALAnnotation {
   }
 }
 
+/**
+ * A SAL macro indicating that a value may be `NULL`.
+ */
 class SALMaybeNull extends SALAnnotation {
   SALMaybeNull() {
     exists(SALMacro m | m = this.getMacro() |
@@ -79,13 +101,29 @@ class SALMaybeNull extends SALAnnotation {
   }
 }
 
+/**
+ * A parameter annotated by one or more SAL annotations.
+ */
+class SALParameter extends Parameter {
+  /** One of this parameter's annotations. */
+  SALAnnotation a;
+
+  SALParameter() { annotatesAt(a, this.getADeclarationEntry(), _, _) }
+
+  predicate isIn() { a.getMacroName().toLowerCase().matches("%\\_in%") }
+
+  predicate isOut() { a.getMacroName().toLowerCase().matches("%\\_out%") }
+
+  predicate isInOut() { a.getMacroName().toLowerCase().matches("%\\_inout%") }
+}
+
 ///////////////////////////////////////////////////////////////////////////////
 // Implementation details
 /**
  * Holds if `a` annotates the declaration entry `d` and
  * its start position is the `idx`th position in `file` that holds a SAL element.
  */
-predicate annotatesAt(SALAnnotation a, DeclarationEntry d, File file, int idx) {
+private predicate annotatesAt(SALAnnotation a, DeclarationEntry d, File file, int idx) {
   annotatesAtPosition(a.(SALElement).getStartPosition(), d, file, idx)
 }
 
@@ -109,22 +147,6 @@ private predicate annotatesAtPosition(SALPosition pos, DeclarationEntry d, File
   )
 }
 
-/**
- * A parameter annotated by one or more SAL annotations.
- */
-class SALParameter extends Parameter {
-  /** One of this parameter's annotations. */
-  SALAnnotation a;
-
-  SALParameter() { annotatesAt(a, this.getADeclarationEntry(), _, _) }
-
-  predicate isIn() { a.getMacroName().toLowerCase().matches("%\\_in%") }
-
-  predicate isOut() { a.getMacroName().toLowerCase().matches("%\\_out%") }
-
-  predicate isInOut() { a.getMacroName().toLowerCase().matches("%\\_inout%") }
-}
-
 /**
  * A SAL element, that is, a SAL annotation or a declaration entry
  * that may have SAL annotations.