C#/Java: Add some more QL docs.

Author: michaelnebel

csharp/ql/src/utils/model-generator/ModelGeneratorUtils.qll

@@ -1,5 +1,8 @@
 import ModelGeneratorUtilsSpecific
 
+/**
+ * Holds if data can flow from `node1` to `node2` either via a read or a write of an intermediate field `f`.
+ */
 predicate isRelevantTaintStep(DataFlow::Node node1, DataFlow::Node node2) {
   exists(DataFlow::Content f |
     readStep(node1, f, node2) and
@@ -14,12 +17,19 @@ predicate isRelevantTaintStep(DataFlow::Node node1, DataFlow::Node node2) {
   exists(DataFlow::Content f | storeStep(node1, f, node2) | DataFlow::containerContent(f))
 }
 
-predicate isRelevantContent(DataFlow::Content f) {
-  isRelevantType(f.(DataFlow::FieldContent).getField().getType()) or
-  isRelevantType(f.(DataFlow::FieldContent).getField().getType()) or
-  DataFlow::containerContent(f)
+/**
+ * Holds if content `c` is either a field or synthetic field of a relevant type
+ * or a container like content.
+ */
+predicate isRelevantContent(DataFlow::Content c) {
+  isRelevantType(c.(DataFlow::FieldContent).getField().getType()) or
+  isRelevantType(c.(DataFlow::FieldContent).getField().getType()) or
+  DataFlow::containerContent(c)
 }
 
+/**
+ * Gets the summary model for `api` with `input`, `output` and `kind`.
+ */
 bindingset[input, output, kind]
 string asSummaryModel(TargetAPI api, string input, string output, string kind) {
   result =
@@ -28,21 +38,33 @@ string asSummaryModel(TargetAPI api, string input, string output, string kind) {
       + kind
 }
 
+/**
+ * Gets the value summary model for `api` with `input` and `output`.
+ */
 bindingset[input, output]
 string asValueModel(TargetAPI api, string input, string output) {
   result = asSummaryModel(api, input, output, "value")
 }
 
+/**
+ * Gets the taint summary model for `api` with `input` and `output`.
+ */
 bindingset[input, output]
 string asTaintModel(TargetAPI api, string input, string output) {
   result = asSummaryModel(api, input, output, "taint")
 }
 
+/**
+ * Gets the sink model for `api` with `input` and `kind`.
+ */
 bindingset[input, kind]
 string asSinkModel(TargetAPI api, string input, string kind) {
   result = asPartialModel(api) + input + ";" + kind
 }
 
+/**
+ * Gets the source model for `api` with `output` and `kind`.
+ */
 bindingset[output, kind]
 string asSourceModel(TargetAPI api, string output, string kind) {
   result = asPartialModel(api) + output + ";" + kind

csharp/ql/src/utils/model-generator/ModelGeneratorUtilsSpecific.qll

@@ -6,6 +6,12 @@ private import semmle.code.csharp.dataflow.internal.DataFlowDispatch
 
 private predicate isRelevantForModels(Callable api) { not api instanceof MainMethod }
 
+/**
+ * A class of Callables that are relevant for generating summary, source and sinks models for.
+ *
+ * In the Standard library and 3rd party libraries it the Callables that can be called
+ * from outside the library itself.
+ */
 class TargetAPI extends Callable {
   TargetAPI() {
     [this.(Modifiable), this.(Accessor).getDeclaration()].isEffectivelyPublic() and
@@ -53,6 +59,10 @@ string asPartialModel(TargetAPI api) {
   )
 }
 
+/**
+ * Holds for type `t` for fields that are relevant as an intermediate
+ * read or write step in the data flow analysis.
+ */
 predicate isRelevantType(Type t) { not t instanceof Enum }
 
 private predicate isPrimitiveTypeUsedForBulkData(Type t) {
@@ -67,12 +77,18 @@ private string parameterAccess(Parameter p) {
   else result = "Argument[" + p.getPosition() + "]"
 }
 
+/**
+ * Gets the model string representation of the parameter node `p`.
+ */
 string parameterNodeAsInput(DataFlow::ParameterNode p) {
   result = parameterAccess(p.asParameter())
   or
   result = "Argument[Qualifier]" and p instanceof InstanceParameterNode
 }
 
+/**
+ * Gets the model string represention of the the return node `node`.
+ */
 string returnNodeAsOutput(ReturnNodeExt node) {
   if node.getKind() instanceof ValueReturnKind
   then result = "ReturnValue"

java/ql/src/utils/model-generator/ModelGeneratorUtils.qll

@@ -1,5 +1,8 @@
 import ModelGeneratorUtilsSpecific
 
+/**
+ * Holds if data can flow from `node1` to `node2` either via a read or a write of an intermediate field `f`.
+ */
 predicate isRelevantTaintStep(DataFlow::Node node1, DataFlow::Node node2) {
   exists(DataFlow::Content f |
     readStep(node1, f, node2) and
@@ -14,12 +17,19 @@ predicate isRelevantTaintStep(DataFlow::Node node1, DataFlow::Node node2) {
   exists(DataFlow::Content f | storeStep(node1, f, node2) | DataFlow::containerContent(f))
 }
 
-predicate isRelevantContent(DataFlow::Content f) {
-  isRelevantType(f.(DataFlow::FieldContent).getField().getType()) or
-  isRelevantType(f.(DataFlow::FieldContent).getField().getType()) or
-  DataFlow::containerContent(f)
+/**
+ * Holds if content `c` is either a field or synthetic field of a relevant type
+ * or a container like content.
+ */
+predicate isRelevantContent(DataFlow::Content c) {
+  isRelevantType(c.(DataFlow::FieldContent).getField().getType()) or
+  isRelevantType(c.(DataFlow::FieldContent).getField().getType()) or
+  DataFlow::containerContent(c)
 }
 
+/**
+ * Gets the summary model for `api` with `input`, `output` and `kind`.
+ */
 bindingset[input, output, kind]
 string asSummaryModel(TargetApi api, string input, string output, string kind) {
   result =
@@ -28,21 +38,33 @@ string asSummaryModel(TargetApi api, string input, string output, string kind) {
       + kind
 }
 
+/**
+ * Gets the value summary model for `api` with `input` and `output`.
+ */
 bindingset[input, output]
 string asValueModel(TargetApi api, string input, string output) {
   result = asSummaryModel(api, input, output, "value")
 }
 
+/**
+ * Gets the taint summary model for `api` with `input` and `output`.
+ */
 bindingset[input, output]
 string asTaintModel(TargetApi api, string input, string output) {
   result = asSummaryModel(api, input, output, "taint")
 }
 
+/**
+ * Gets the sink model for `api` with `input` and `kind`.
+ */
 bindingset[input, kind]
 string asSinkModel(TargetApi api, string input, string kind) {
   result = asPartialModel(api) + input + ";" + kind
 }
 
+/**
+ * Gets the source model for `api` with `output` and `kind`.
+ */
 bindingset[output, kind]
 string asSourceModel(TargetApi api, string output, string kind) {
   result = asPartialModel(api) + output + ";" + kind

java/ql/src/utils/model-generator/ModelGeneratorUtilsSpecific.qll

@@ -42,6 +42,12 @@ predicate isRelevantForModels(Callable api) {
   not api instanceof MainMethod
 }
 
+/**
+ * A class of Callables that are relevant for generating summary, source and sinks models for.
+ *
+ * In the Standard library and 3rd party libraries it the Callables that can be called
+ * from outside the library itself.
+ */
 class TargetApi extends Callable {
   TargetApi() {
     this.isPublic() and
@@ -90,6 +96,10 @@ private predicate isPrimitiveTypeUsedForBulkData(Type t) {
   t.getName().regexpMatch("byte|char|Byte|Character")
 }
 
+/**
+ * Holds for type `t` for fields that are relevant as an intermediate
+ * read or write step in the data flow analysis.
+ */
 predicate isRelevantType(Type t) {
   not t instanceof TypeClass and
   not t instanceof EnumType and
@@ -122,12 +132,18 @@ private string parameterAccess(Parameter p) {
     else result = "Argument[" + p.getPosition() + "]"
 }
 
+/**
+ * Gets the model string representation of the parameter node `p`.
+ */
 string parameterNodeAsInput(DataFlow::ParameterNode p) {
   result = parameterAccess(p.asParameter())
   or
   result = "Argument[-1]" and p instanceof DataFlow::InstanceParameterNode
 }
 
+/**
+ * Gets the model string represention of the the return node `node`.
+ */
 string returnNodeAsOutput(ReturnNodeExt node) {
   if node.getKind() instanceof ValueReturnKind
   then result = "ReturnValue"