C#: Add QlDoc for predicates in Helpers

tamasvajk · tamasvajk · commit ce68e458e0ef · 2020-08-26T11:21:44.000+02:00
diff --git a/csharp/ql/src/Linq/Helpers.qll b/csharp/ql/src/Linq/Helpers.qll
@@ -6,18 +6,32 @@
 import csharp
 
 //#################### PREDICATES ####################
-Stmt firstStmt(ForeachStmt fes) {
+private Stmt firstStmt(ForeachStmt fes) {
   if fes.getBody() instanceof BlockStmt
   then result = fes.getBody().(BlockStmt).getStmt(0)
   else result = fes.getBody()
 }
 
+private int numStmts(ForeachStmt fes) {
+  if fes.getBody() instanceof BlockStmt
+  then result = count(fes.getBody().(BlockStmt).getAStmt())
+  else result = 1
+}
+
+/** Holds if the type's qualified name is "System.Linq.Enumerable" */
 predicate isEnumerableType(ValueOrRefType t) { t.hasQualifiedName("System.Linq.Enumerable") }
 
+/** Holds if the type's qualified name starts with "System.Collections.Generic.IEnumerable" */
 predicate isIEnumerableType(ValueOrRefType t) {
   t.getQualifiedName().matches("System.Collections.Generic.IEnumerable%")
 }
 
+/**
+ * Holds if `ForeachStmt` could be converted to a `.All()` call. That is,
+ * the `ForeachStmt` contains a single `if` with a condition that accesses
+ * the loop variable and with a body that assigns `false` to a variable and
+ * `break`s out of the `foreach`.
+ */
 predicate missedAllOpportunity(ForeachStmt fes) {
   exists(IfStmt is |
     // The loop contains an if statement with no else case, and nothing else.
@@ -36,6 +50,11 @@ predicate missedAllOpportunity(ForeachStmt fes) {
   )
 }
 
+/**
+ * Holds if `ForeachStmt` could be converted to a `.Cast()` call. That is, the
+ * loop variable is accessed only in the first statement of the block, and the
+ * access is a cast. The first statement needs to be a `LocalVariableDeclStmt`.
+ */
 predicate missedCastOpportunity(ForeachStmt fes, LocalVariableDeclStmt s) {
   s = firstStmt(fes) and
   forex(VariableAccess va | va = fes.getVariable().getAnAccess() |
@@ -47,6 +66,12 @@ predicate missedCastOpportunity(ForeachStmt fes, LocalVariableDeclStmt s) {
   )
 }
 
+/**
+ * Holds if `ForeachStmt` could be converted to an `.OfType()` call. That is, the
+ * loop variable is accessed only in the first statement of the block, and the
+ * access is a cast with the `as` operator. The first statement needs to be a
+ * `LocalVariableDeclStmt`.
+ */
 predicate missedOfTypeOpportunity(ForeachStmt fes, LocalVariableDeclStmt s) {
   s = firstStmt(fes) and
   forex(VariableAccess va | va = fes.getVariable().getAnAccess() |
@@ -58,6 +83,11 @@ predicate missedOfTypeOpportunity(ForeachStmt fes, LocalVariableDeclStmt s) {
   )
 }
 
+/**
+ * Holds if `ForeachStmt` could be converted to a `.Select()` call. That is, the
+ * loop variable is accessed only in the first statement of the block, and the
+ * access is not a cast. The first statement needs to be a `LocalVariableDeclStmt`.
+ */
 predicate missedSelectOpportunity(ForeachStmt fes, LocalVariableDeclStmt s) {
   s = firstStmt(fes) and
   forex(VariableAccess va | va = fes.getVariable().getAnAccess() |
@@ -66,6 +96,12 @@ predicate missedSelectOpportunity(ForeachStmt fes, LocalVariableDeclStmt s) {
   not s.getAVariableDeclExpr().getInitializer() instanceof Cast
 }
 
+/**
+ * Holds if `ForeachStmt` could be converted to a `.Where()` call. That is, first
+ * statement of the loop is an `if`, which accesses the loop variable, and the body
+ * of the `if` is either a `continue` or there's nothing else in the loop than the
+ * `if`.
+ */
 predicate missedWhereOpportunity(ForeachStmt fes, IfStmt is) {
   // The very first thing the foreach loop does is test its iteration variable.
   is = firstStmt(fes) and
@@ -82,12 +118,6 @@ predicate missedWhereOpportunity(ForeachStmt fes, IfStmt is) {
   )
 }
 
-int numStmts(ForeachStmt fes) {
-  if fes.getBody() instanceof BlockStmt
-  then result = count(fes.getBody().(BlockStmt).getAStmt())
-  else result = 1
-}
-
 //#################### CLASSES ####################
 /** A LINQ Any(...) call. */
 class AnyCall extends MethodCall {
