Python: Add QL doc

yoff · yoff · commit 8eacef34678e · 2020-08-17T12:01:36.000+02:00
diff --git a/python/ql/src/semmle/python/Magic.qll b/python/ql/src/semmle/python/Magic.qll
@@ -1,12 +1,33 @@
+/**
+ * Provides support for magic methods.
+ * This is done in two steps:
+ *   - A subset of `ControlFlowNode`s are labelled as potentially corresponding to
+ *     a magic method call (by being an instance of `MagicMethod::Potential`).
+ *   - A subset of the potential magic method calls are labelled as being actual
+ *     magic method calls (`MagicMethod::Actual`) if the appropriate method is defined.
+ */
+
 import python
 
+/**
+ * Machinery for detecting magic method calls.
+ * Extend `MagicMethod::Potential` to capture more cases.
+ */
 module MagicMethod {
+  /** A control flow node which might correpsond to a magic method call. */
   abstract class Potential extends ControlFlowNode {
+    /** Gets the name of the method that would be called */
     abstract string getMagicMethodName();
+
+    /** Gets the controlflow node that would be passed as the specified argument. */
     abstract ControlFlowNode getArg(int n);
+
+    /** Gets the control flow node corresponding to the instance
+     * that would define the magic method. */
     ControlFlowNode getSelf() { result = this.getArg(0) }
   }
 
+  /** A control flow node corresponding to a magic method call. */
   class Actual extends ControlFlowNode {
     Value resolvedMagicMethod;
 
@@ -17,10 +38,12 @@ module MagicMethod {
       )
     }
 
+    /** The method that is called. */
     Value getResolvedMagicMethod() { result = resolvedMagicMethod }
   }
 }
 
+/** A binary expression node that might correspond to a magic method call. */
 class MagicBinOp extends MagicMethod::Potential, BinaryExprNode {
   Operator operator;
 
