Improve code comments

Author: jorgectf

python/ql/src/experimental/semmle/python/Concepts.qll

@@ -24,8 +24,14 @@ module RegexExecution {
    * extend `RegexExecution` instead.
    */
   abstract class Range extends DataFlow::Node {
+    /**
+     * Gets the argument containing the executed expression.
+     */
     abstract DataFlow::Node getRegexNode();
 
+    /**
+     * Gets the library used to execute the regular expression.
+     */
     abstract string getRegexModule();
   }
 }
@@ -55,6 +61,9 @@ module RegexEscape {
    * extend `RegexEscape` instead.
    */
   abstract class Range extends DataFlow::Node {
+    /**
+     * Gets the argument containing the escaped expression.
+     */
     abstract DataFlow::Node getRegexNode();
   }
 }

python/ql/src/experimental/semmle/python/frameworks/Stdlib.qll

@@ -10,20 +10,33 @@ private import semmle.python.dataflow.new.RemoteFlowSources
 private import experimental.semmle.python.Concepts
 private import semmle.python.ApiGraphs
 
-/** Provides models for the Python standard library. */
+/**
+ * Provides models for Python's `re` library.
+ *
+ * See https://docs.python.org/3/library/re.html
+ */
 private module Re {
-  /** List of re methods. */
-  private class ReMethods extends string {
-    ReMethods() {
+  /**
+   * List of `re` methods immediately executing an expression.
+   *
+   * See https://docs.python.org/3/library/re.html#module-contents
+   */
+  private class RegexExecutionMethods extends string {
+    RegexExecutionMethods() {
       this in ["match", "fullmatch", "search", "split", "findall", "finditer", "sub", "subn"]
     }
   }
 
+  /**
+   * A class to find `re` methods immediately executing an expression.
+   *
+   * See `RegexExecutionMethods`
+   */
   private class DirectRegex extends DataFlow::CallCfgNode, RegexExecution::Range {
     DataFlow::Node regexNode;
 
     DirectRegex() {
-      this = API::moduleImport("re").getMember(any(ReMethods m)).getACall() and
+      this = API::moduleImport("re").getMember(any(RegexExecutionMethods m)).getACall() and
       regexNode = this.getArg(0)
     }
 
@@ -32,6 +45,14 @@ private module Re {
     override string getRegexModule() { result = "re" }
   }
 
+  /**
+   * A class to find `re` methods immediately executing an expression from a
+   * compiled expression by `re.compile`.
+   *
+   * See `RegexExecutionMethods`
+   *
+   * See https://docs.python.org/3/library/re.html#regular-expression-objects
+   */
   private class CompiledRegex extends DataFlow::CallCfgNode, RegexExecution::Range {
     DataFlow::Node regexNode;
     DataFlow::CallCfgNode regexMethod;
@@ -41,7 +62,7 @@ private module Re {
         this.getFunction() = reMethod and
         patternCall = API::moduleImport("re").getMember("compile").getACall() and
         patternCall = reMethod.getObject().getALocalSource() and
-        reMethod.getAttributeName() instanceof ReMethods and
+        reMethod.getAttributeName() instanceof RegexExecutionMethods and
         regexNode = patternCall.getArg(0)
       )
     }
@@ -51,6 +72,11 @@ private module Re {
     override string getRegexModule() { result = "re" }
   }
 
+  /**
+   * A class to find `re` methods escaping an expression.
+   *
+   * See https://docs.python.org/3/library/re.html#re.escape
+   */
   class ReEscape extends DataFlow::CallCfgNode, RegexEscape::Range {
     DataFlow::Node regexNode;
     DataFlow::CallCfgNode escapeMethod;

python/ql/src/experimental/semmle/python/security/injection/RegexInjection.qll

@@ -9,6 +9,11 @@ import semmle.python.dataflow.new.DataFlow
 import semmle.python.dataflow.new.TaintTracking
 import semmle.python.dataflow.new.RemoteFlowSources
 
+/**
+ * A class to find methods executing regular expressions.
+ *
+ * See `RegexExecution`
+ */
 class RegexInjectionSink extends DataFlow::Node {
   string regexModule;
   Attribute regexMethod;