Rust: Add much more detailed code comments, since these are examples.

Author: geoffw0

rust/ql/examples/snippets/empty_if.ql

@@ -8,8 +8,11 @@
 
 import rust
 
+// find 'if' statements...
 from IfExpr ifExpr
 where
+  // where the 'then' branch is empty
   ifExpr.getThen().(BlockExpr).getStmtList().getNumberOfStmtOrExpr() = 0 and
+  // and no 'else' branch exists
   not exists(ifExpr.getElse())
 select ifExpr, "This 'if' expression is redundant."

rust/ql/examples/snippets/simple_constant_password.ql

@@ -1,7 +1,7 @@
 /**
  * @name Constant password
  * @description Finds places where a string literal is used in a function call
- *              argument named something like "password".
+ *              argument that looks like a password.
  * @id rust/examples/simple-constant-password
  * @tags example
  */
@@ -10,8 +10,23 @@ import rust
 import codeql.rust.dataflow.DataFlow
 import codeql.rust.dataflow.TaintTracking
 
+/**
+ * A data flow configuration for tracking flow from a string literal to a function
+ * call argument that looks like a password. For example:
+ * ```
+ * fn set_password(password: &str) { ... }
+ *
+ * ...
+ *
+ * let pwd = "123456"; // source
+ * set_password(pwd); // sink (argument 0)
+ * ```
+ */
 module ConstantPasswordConfig implements DataFlow::ConfigSig {
-  predicate isSource(DataFlow::Node node) { node.asExpr().getExpr() instanceof StringLiteralExpr }
+  predicate isSource(DataFlow::Node node) {
+    // `node` is a string literal
+    node.asExpr().getExpr() instanceof StringLiteralExpr
+  }
 
   predicate isSink(DataFlow::Node node) {
     // `node` is an argument whose corresponding parameter name matches the pattern "pass%"
@@ -23,8 +38,10 @@ module ConstantPasswordConfig implements DataFlow::ConfigSig {
   }
 }
 
+// instantiate the data flow configuration as a global taint tracking module
 module ConstantPasswordFlow = TaintTracking::Global<ConstantPasswordConfig>;
 
+// report flows from sources to sinks
 from DataFlow::Node sourceNode, DataFlow::Node sinkNode
 where ConstantPasswordFlow::flow(sourceNode, sinkNode)
 select sinkNode, "The value $@ is used as a constant password.", sourceNode, sourceNode.toString()

rust/ql/examples/snippets/simple_sql_injection.ql

@@ -1,8 +1,7 @@
 /**
  * @name Database query built from user-controlled sources
  * @description Finds places where a value from a remote or local user input
- *              is used as an argument to the `sqlx_core::query::query`
- *              function.
+ *              is used as the first argument of a call to `sqlx_core::query::query`.
  * @id rust/examples/simple-sql-injection
  * @tags example
  */
@@ -12,19 +11,29 @@ import codeql.rust.dataflow.DataFlow
 import codeql.rust.dataflow.TaintTracking
 import codeql.rust.Concepts
 
+/**
+ * A data flow configuration for tracking flow from a user input (threat model
+ * source) to the first argument of a call to `sqlx_core::query::query`.
+ */
 module SqlInjectionConfig implements DataFlow::ConfigSig {
-  predicate isSource(DataFlow::Node node) { node instanceof ActiveThreatModelSource }
+  predicate isSource(DataFlow::Node node) {
+    // `node` is a user input (threat model source)
+    node instanceof ActiveThreatModelSource
+  }
 
   predicate isSink(DataFlow::Node node) {
+    // `node` is the first argument of a call to `sqlx_core::query::query`
     exists(CallExpr call |
       call.getStaticTarget().getCanonicalPath() = "sqlx_core::query::query" and
       call.getArg(0) = node.asExpr().getExpr()
     )
   }
 }
 
+// instantiate the data flow configuration as a global taint tracking module
 module SqlInjectionFlow = TaintTracking::Global<SqlInjectionConfig>;
 
+// report flows from sources to sinks
 from DataFlow::Node sourceNode, DataFlow::Node sinkNode
 where SqlInjectionFlow::flow(sourceNode, sinkNode)
 select sinkNode, "This query depends on a $@.", sourceNode, "user-provided value"