C#: Add QL Doc to the primary predicate used for capturing flow.

Author: michaelnebel

csharp/ql/src/utils/model-generator/CaptureSummaryModelsQuery.ql

@@ -4,8 +4,85 @@
  * @id csharp/utils/model-generator/summary-models
  */
 
-import CaptureSummaryModels
+private import CaptureSummaryModels
 
+/**
+ * Capture fluent APIs that return `this`.
+ * Example of a fluent API:
+ * ```
+ * public class BasicFlow {
+ *   public BasicFlow ReturnThis(object input)
+ *   {
+ *     // some side effect
+ *     return this;
+ *   }
+ * ```
+ * Captured Model:
+ * ```
+ * Summaries;BasicFlow;false;ReturnThis;(System.Object);Argument[Qualifier];ReturnValue;value
+ * ```
+ * Capture APIs that transfer taint from an input parameter to an output return
+ * value or parameter.
+ * Allows a sequence of read steps followed by a sequence of store steps.
+ *
+ * Examples:
+ *
+ * ```
+ * public class BasicFlow {
+ *   private string tainted;
+ *
+ *   public String ReturnField()
+ *   {
+ *     return tainted;
+ *   }
+ *
+ *   public void AssignFieldToArray(object[] target)
+ *   {
+ *     target[0] = tainted;
+ *   }
+ * }
+ * ```
+ * Captured Models:
+ * ```
+ * Summaries;BasicFlow;false;ReturnField;();Argument[Qualifier];ReturnValue;taint |
+ * Summaries;BasicFlow;false;AssignFieldToArray;(System.Object[]);Argument[Qualifier];Argument[0].Element;taint
+ * ```
+ *
+ * ```
+ * public class BasicFlow {
+ *   private string tainted;
+ *
+ *   public void SetField(string s)
+ *   {
+ *     tainted = s;
+ *   }
+ * }
+ * ```
+ * Captured Model:
+ * `Summaries;BasicFlow;false;SetField;(System.String);Argument[0];Argument[Qualifier];taint`
+ *
+ * ```
+ * public class BasicFlow {
+ *   public void ReturnSubstring(string s)
+ *   {
+ *     return s.Substring(0, 1);
+ *   }
+ * }
+ * ```
+ * Captured Model:
+ * `Summaries;BasicFlow;false;ReturnSubstring;(System.String);Argument[0];ReturnValue;taint`
+ *
+ * ```
+ * public class BasicFlow {
+ *    public void AssignToArray(int data, int[] target)
+ *    {
+ *        target[0] = data;
+ *    }
+ * }
+ * ```
+ * Captured Model:
+ * `Summaries;BasicFlow;false;AssignToArray;(System.Int32,System.Int32[]);Argument[0];Argument[1].Element;taint`
+ */
 private string captureFlow(TargetAPI api) {
   result = captureQualifierFlow(api) or
   result = captureThroughFlow(api)

java/ql/src/utils/model-generator/CaptureSummaryModelsQuery.ql

@@ -4,7 +4,7 @@
  * @id java/utils/model-generator/summary-models
  */
 
-import CaptureSummaryModels
+private import CaptureSummaryModels
 
 /**
  * Capture fluent APIs that return `this`.