Python: add comments

python/ql/test/experimental/dataflow/variable-capture/dict.py

@@ -1,3 +1,6 @@
+# Here we test writing to a captured variable via a dictionary (see `out`).
+# We also test reading one captured variable and writing the value to another (see `through`).
+
 # All functions starting with "test_" should run and execute `print("OK")` exactly once.
 # This can be checked by running validTest.py.
 
@@ -29,7 +32,7 @@ def SINK_F(x):
         print("OK")
 
 
-def Out():
+def out():
     sinkO1 = { "x": "" }
     def captureOut1():
         sinkO1["x"] = SOURCE
@@ -56,10 +59,10 @@ def Out():
     SINK_F(nonSink0["x"])
 
 @expects(4)
-def test_Out():
-    Out()
+def test_out():
+    out()
 
-def Through(tainted):
+def through(tainted):
     sinkO1 = { "x": "" }
     def captureOut1():
         sinkO1["x"] = tainted
@@ -86,5 +89,5 @@ def Through(tainted):
     SINK_F(nonSink0["x"])
 
 @expects(4)
-def test_Through():
-    Through(SOURCE)
+def test_through():
+    through(SOURCE)

python/ql/test/experimental/dataflow/variable-capture/in.py

@@ -1,3 +1,5 @@
+# Here we test the case where a captured variable is being read.
+
 # All functions starting with "test_" should run and execute `print("OK")` exactly once.
 # This can be checked by running validTest.py.
 
@@ -28,7 +30,7 @@ def SINK_F(x):
     else:
         print("OK")
 
-
+# Capture the parameter of an outer function.
 def inParam(tainted):
     def captureIn1():
         sinkI1 = tainted
@@ -59,6 +61,7 @@ def inParam(tainted):
 def test_inParam():
     inParam(SOURCE)
 
+# Capture the local variable of an outer function.
 def inLocal():
     tainted = SOURCE
 

python/ql/test/experimental/dataflow/variable-capture/nonlocal.py

@@ -1,3 +1,6 @@
+# Here we test writing to a captured variable via the `nonlocal` keyword (see `out`).
+# We also test reading one captured variable and writing the value to another (see `through`).
+
 # All functions starting with "test_" should run and execute `print("OK")` exactly once.
 # This can be checked by running validTest.py.
 
@@ -29,7 +32,7 @@ def SINK_F(x):
         print("OK")
 
 
-def Out():
+def out():
     sinkO1 = ""
     def captureOut1():
         nonlocal sinkO1
@@ -60,10 +63,10 @@ def Out():
     SINK_F(nonSink0)
 
 @expects(4)
-def test_Out():
-    Out()
+def test_out():
+    out()
 
-def Through(tainted):
+def through(tainted):
     sinkO1 = ""
     def captureOut1():
         nonlocal sinkO1
@@ -94,5 +97,5 @@ def Through(tainted):
     SINK_F(nonSink0)
 
 @expects(4)
-def test_Through():
-    Through(SOURCE)
+def test_through():
+    through(SOURCE)