Cleaned up a bit of dead code in CodeUnit and commented a lot of code

Author: isc-cge

cls/TestCoverage/Data/CodeUnit.cls

@@ -133,17 +133,20 @@ ClassMethod GetCurrentByName(pInternalName As %String, pSourceNamespace As %Stri
 
 
 		If (tType = "PY") {
+			// fill in the Lines property of this CodeUnit
 			set tPointer = 0
 			While $ListNext(pDocumentText, tPointer, tCurLine) {
 				do pCodeUnit.Lines.Insert(tCurLine)
 			}
 
 			do pCodeUnit.Lines.Insert("")
 
+			// Filling in the MethodMap and LineToMethodMap properties 
 			Set ClassName = $Piece(tName,".", *)
 			Set tMethodInfo = ##class(TestCoverage.Utils).GetPythonMethodMapping(pDocumentText, ClassName)
-			Set tLineToMethodInfo = tMethodInfo."__getitem__"(0)
-			Set tMethodMapInfo = tMethodInfo."__getitem__"(1)
+			// tMethodInfo is a python tuple of (line to method info, method map info) 
+			Set tLineToMethodInfo = tMethodInfo."__getitem__"(0) // a python builtins list where the item at index i is the name of the method that line i is a part of 
+			Set tMethodMapInfo = tMethodInfo."__getitem__"(1) // a python builtins dict with key = method name, value = the line number of its definition
 			for i=1:1:$listlength(pDocumentText) {
 				Set tMethod = tLineToMethodInfo."__getitem__"(i)
 				Do pCodeUnit.LineToMethodMap.SetAt(tMethod,i)
@@ -157,12 +160,6 @@ ClassMethod GetCurrentByName(pInternalName As %String, pSourceNamespace As %Stri
 				Do pCodeUnit.MethodMap.SetAt(tStartLine,tMethod)
 				Set tExecutableFlags(tStartLine) = 0
 				Do pCodeUnit.MethodEndMap.SetAt(tEndLine, tMethod)
-
-				Set tMethodMask = ""
-				for j = tStartLine:1:tEndLine {
-					Set $Bit(tMethodMask,j) = 1
-				}
-				Set tMethodSignature = $list(pDocumentText, tStartLine)
 			}
 		}
 		Else {
@@ -252,10 +249,8 @@ Method UpdatePyExecutableLines(pName As %String, ByRef pPyCodeUnit) As %Status
 		Set tBitString = ""
 		If (##class(TestCoverage.Manager).HasPython(pName)) {
 
-			// snapshot the Python CodeUnit for it 
 			Set tFromHash = pPyCodeUnit.Hash
 			Set tToHash = ..Hash 
-			// now bring over the executable lines 
 
 			&sql(
 				DECLARE C1 CURSOR FOR
@@ -352,12 +347,15 @@ Method UpdateSourceMap(pSourceNamespace As %String, ByRef pCache) As %Status
 
 			set tClass = ..Name
 			Set tSourceUnits(tClass_".CLS") = ""
+			// we'll need the MethodMap from the .CLS CodeUnit to figure out the line mappings
 			$$$ThrowOnError(..GetCurrentByName(tClass _ ".CLS", pSourceNamespace, .pCLSCodeUnit, .pCLSCache))
 			// we'll do the mappings from the .py to the .cls direction, so that we don't iterate over objectscript lines
 			Set tMethod = ""
 			Do ..MethodMap.GetNext(.tMethod)
 			while (tMethod '= "") 
 			{
+				// for each method in the .py file, we'll find the line number of the corresponding method (guaranteed to be unique) in the .cls file
+				// and then map each line in the .py file to each line in the .cls file by just going 1 by 1 down the lines 
 				Set tCLSMethodNum = pCLSCodeUnit.MethodMap.GetAt(tMethod)
 				Set tMethodStart = ..MethodMap.GetAt(tMethod)
 				Set tMethodEnd = ..MethodEndMap.GetAt(tMethod)
@@ -506,7 +504,7 @@ Method UpdateComplexity() As %Status
 
 		// python methods
 		If (##class(TestCoverage.Manager).HasPython(..Name)) {
-			do ##class(TestCoverage.Data.CodeUnit).GetCurrentByName(..Name _ ".PY", , .pPyCodeUnit, )
+			do ##class(TestCoverage.Data.CodeUnit).GetCurrentByName(..Name _ ".PY", , .pPyCodeUnit, ) // need the source code for the python
 			set tDocumentText = pPyCodeUnit.Lines.Serialize()
 			set tMethodComplexities = ..GetPythonComplexities(tDocumentText)
 		}
@@ -533,6 +531,7 @@ Method UpdateComplexity() As %Status
 	Quit tSC
 }
 
+/// returns a python dict with (key, value) = (method name, complexity) for each python method
 ClassMethod GetPythonComplexities(pDocumentText) [ Language = python ]
 {
     from radon.complexity import cc_visit
@@ -578,8 +577,8 @@ ClassMethod GetCurrentHash(pName As %String, pType As %String, Output pHash As %
 				// includes the class compilation signature.
 				Set pHash = ..HashArrayRange(.pCodeArray,5,pName_"."_pType,.tSizeHint)
 			} ElseIf (pType = "PY") {
-				Merge pCodeArray = ^ROUTINE(pName_".py",0)
-				set tSizeHint = ^ROUTINE(pName_".py",0,0)
+				Merge pCodeArray = ^ROUTINE(pName_".py",0) // the python source code 
+				set tSizeHint = ^ROUTINE(pName_".py",0,0) // the number of lines in the python code 
 				set pHash = ..HashArrayRange(.pCodeArray, ,pName_".py", .pSizeHint)
 			} Else {
 				// Give standard descriptive error about the type being invalid.

cls/TestCoverage/Data/Coverage.cls

@@ -100,6 +100,8 @@ ClassMethod StoreIntCoverage(pRun As %Integer, pTestPath As %String, pName As %S
 			$$$ThrowOnError(tSC)
 		}
 		Else { // If pType = "PY"
+			//^IRIS.TEMP.TestCoveragePy(ClassName) contains the number of covered lines in this class
+			//^IRIS.TEMP.TestCoveragePy(ClassName, i) in increasing order contain the line numbers for the covered lines
 			if $Data(^IRIS.TEMP.TestCoveragePY(pName)) {
 				for i = 1:1:(^IRIS.TEMP.TestCoveragePY(pName)-1) {
 					Set tLineNumber = ^IRIS.TEMP.TestCoveragePY(pName, i)

cls/TestCoverage/Utils.cls

@@ -82,12 +82,6 @@ ClassMethod Snapshot(pIntRoutines As %List, Output pRelevantRoutines As %List =
 {
 	Set tSC = $$$OK
 	Try {
-		// For debugging use only: no parallelization
-		#; Set tPointer = 0
-		#; While $ListNext(pIntRoutines, tPointer, tIntRoutine) {
-		#; 	do ##class(TestCoverage.Data.CodeUnit).GetCurrentByName(tIntRoutine_".INT")
-		#; }
-
 		#dim tSnapshotQueue As %SYSTEM.WorkMgr
 		Set tSnapshotQueue = $System.WorkMgr.Initialize(,.tSC)
 		$$$ThrowOnError(tSC)
@@ -133,30 +127,6 @@ ClassMethod Snapshot(pIntRoutines As %List, Output pRelevantRoutines As %List =
 			Set pRelevantRoutines = pRelevantRoutines _ $ListBuild(tIntRoutine)
 		}
 
-		// snapshot all the compiled python CodeUnits
-		#; Set tSnapshotQueue = $System.WorkMgr.Initialize(,.tSC)
-		#; $$$ThrowOnError(tSC)
-		#; Set tPointer = 0
-		#; While $ListNext(pPyRelevantRoutines,tPointer,tPyRoutine) {
-		#; 	Set tSC = tSnapshotQueue.Queue("##class(TestCoverage.Data.CodeUnit).GetCurrentByName",tPyRoutine_".PY")
-		#; 	$$$ThrowOnError(tSC)
-		#; }
-		
-		#; Set tSC = tSnapshotQueue.WaitForComplete()
-		#; $$$ThrowOnError(tSC)
-
-		// update the executable lines for the .cls files that have python -- TODO: make the UpdatePyExecutableLines method not rely on knowing the .cls and .py CodeUnits beforehand
-		#; Set tSnapshotQueue = $System.WorkMgr.Initialize(,.tSC)
-		#; $$$ThrowOnError(tSC)
-		#; Set tPointer = 0
-		#; While $ListNext(pPyRelevantRoutines,tPointer,tClass) {
-		#; 	Set tSC = tSnapshotQueue.Queue("##class(TestCoverage.Data.CodeUnit).UpdatePyExecutableLines",tClass)
-		#; 	$$$ThrowOnError(tSC)
-		#; }
-		
-		#; Set tSC = tSnapshotQueue.WaitForComplete()
-		#; $$$ThrowOnError(tSC)
-
 		Write !
 	} Catch e {
 		Set tSC = e.AsStatus()
@@ -443,6 +413,9 @@ ClassMethod CodeArrayToList(ByRef pCodeArray, Output pDocumentText As %List)
 	quit
 }
 
+/// returns a python tuple of (line to method info, method map info) 
+/// linetomethodinfo: a python builtins list where the item at index i is the name of the method that line i is a part of 
+/// methodmapinfo: a python builtins dict with key = method name, value = the line number of its definition
 ClassMethod GetPythonMethodMapping(pDocumentText, ClassName) [ Language = python ]
 {
 	import iris
@@ -454,13 +427,13 @@ ClassMethod GetPythonMethodMapping(pDocumentText, ClassName) [ Language = python
 	source = ''.join(source_lines)
 	tree = ast.parse(source)
 	line_function_map = [None] * (len(source_lines)+2)
-	method_map = {}
+	method_map = {} # dictionary from the method name to its start and ending line number
 
 	class FunctionMapper(ast.NodeVisitor):
 		def __init__(self):
 			self.current_class = None
 			self.current_function = None
-			self.outermost_function = None
+			self.outermost_function = None # for objectscript purposes, we only care about the outer level functions/methods
 
 		def visit_ClassDef(self, node):
 			prev_class = self.current_class
@@ -471,7 +444,7 @@ ClassMethod GetPythonMethodMapping(pDocumentText, ClassName) [ Language = python
 		def visit_FunctionDef(self, node):
 			if self.outermost_function is None:
 				self.outermost_function = node.name
-				method_map[node.name] = (node.lineno-1, node.end_lineno-1)
+				method_map[node.name] = (node.lineno-1, node.end_lineno-1) 
 
 			self.current_function = node.name
 			for lineno in range(node.lineno, node.end_lineno + 1):
@@ -526,7 +499,7 @@ ClassMethod GetPythonLineExecutableFlags(pDocumentText) [ Language = python ]
 										ast.AsyncWith, ast.Raise, ast.Try, ast.Assert, 
 										ast.Import, ast.ImportFrom, ast.Pass, 
 										ast.Break, ast.Continue, ast.Delete, ast.Yield, 
-										ast.YieldFrom, ast.Await, ast.Nonlocal)): # all executable
+										ast.YieldFrom, ast.Await, ast.Nonlocal)): # all executable (determined manually)
 					executable_lines.add(node.lineno)
 				elif isinstance(node, ast.ExceptHandler): # except (but not finally) is executable
 					executable_lines.add(node.lineno)