docs: complete code documentation

Signed-off-by: Zvi Grinberg <zgrinber@redhat.com>

Author: zvigrinberg

src/concurrent_executor.py

@@ -8,7 +8,9 @@
 logger = logging.getLogger(__name__)
 
 class ExecutionInput:
-
+    """
+    Data model for one test input being sent as request to the agent service
+    """
     def __init__(self,number : int,  test: dict, payload: dict, request_id: str):
         self.number = number
         self.test = test
@@ -17,7 +19,9 @@ def __init__(self,number : int,  test: dict, payload: dict, request_id: str):
 
 
 class ExecutionOutput:
-
+    """
+    Data model for one test output being received as result from the agent service
+    """
     def __init__(self, number: int, response: dict, request_id: str, test: dict) -> None:
         self.number = number
         self.response = response
@@ -26,12 +30,26 @@ def __init__(self, number: int, response: dict, request_id: str, test: dict) ->
         self.intercepted_error = ""
 
 class ConcurrentExecutor:
+
+    """
+    Class that responsible for executing requests concurrently
+
+    Args:
+            execution: the Execution instance that can send and orchestrate sending requests
+            num_of_processes: Number of concurrent requests that will be sent at once to agent, by default, it's 2.
+
+    """
     def __init__(self, execution: Execution, num_of_processes: int = 2):
 
         self.execution = execution
         self.num_of_process =  num_of_processes
-
     def execute_one_request(self, payload_data: ExecutionInput):
+        """
+         This method in charge of sending one request
+        :param payload_data: input data containing payload of request and its metadata.
+        :return: output object containing result from agent, or crafted output object
+         in case error was intercepted on invocation.
+        """
         try:
             logger.info(f"Sending Request of test #{payload_data.number},"
                         f"Test-id={Execution.generate_test_id(payload_data.payload)}")
@@ -57,7 +75,7 @@ def run_requests(self, execution_payloads: list[ExecutionInput]) -> list[Executi
         """
 
         with ThreadPoolExecutor(max_workers=self.num_of_process) as pool:
-
+            # Distribute the tests' requests payloads between the threads workers.
             results =  pool.map(self.execute_one_request, execution_payloads)
             return list(results)
 

src/it_results_interpreter.py

@@ -37,7 +37,21 @@
 }
 
 class IntegrationTestsResultsInterpreter:
+    """
+    This class responsible for each non-skipped test entry:
+    1. Match its result with its expectation
+    2. If it's a mismatch, prints a red message to log with test entry id,  and increment failures.
+    3. If it's a match, prints a green message to log with test entry id.
+    4. For tests that their invocation failed, the mismatch will be guaranteed.
+
+    """
     def __init__(self, tests: list[dict], results: list[dict], strict_mode: bool = False):
+        """
+
+        :param tests: List of tests entries from input file
+        :param results: List of tests results aggregated and retrieved from agent service
+        :param strict_mode: Whether to enable strict mode matching for comparison between tests and results.
+        """
         self.tests = tests
         self.results = results
         self.failures = 0
@@ -112,6 +126,13 @@ def prepare_common_result_fields(self, result: dict, result_index: int):
         return result_fields
 
     def __match_one_result_with_test(self, test_fields: dict, result_fields: dict) -> bool:
+        """
+        This method gets a test entry, and its corresponding result entry from agent,
+         and returns whether the test succeeded or not.
+        :param test_fields: dict containing test entry data and metadata
+        :param result_fields: dict containing result output, data and metadata
+        :return: True if test succeeded, and False if test failed.
+        """
         (actual_result, allowed_labels, expected_label,
          justification_label, test_expected_result) = self.get_test_to_be_matched_fields(result_fields, test_fields)
         if test_expected_result == actual_result:
@@ -126,6 +147,13 @@ def __match_one_result_with_test(self, test_fields: dict, result_fields: dict) -
             return False
 
     def get_test_to_be_matched_fields(self, result_fields: dict, test_fields: dict) -> tuple[str, list, str, str, str]:
+        """
+        This method extract the fields from test entry and the corresponding result entry
+         that are important for comparison.
+        :param result_fields: result entry fields dictionary
+        :param test_fields: test entry fields dictionary
+        :return: tuple containing the fields from both dicts that are required for comparison.
+        """
         justification_status = result_fields.get(JUSTIFICATION_STATUS)
         justification_label: str = result_fields.get(JUSTIFICATION_LABEL)
         allowed_labels = test_fields.get(ALLOWED_DEVIATION_LABELS, [])
@@ -135,13 +163,25 @@ def get_test_to_be_matched_fields(self, result_fields: dict, test_fields: dict)
         return actual_result, allowed_labels, expected_label, justification_label, test_expected_result
 
     def build_common_test_header(self, test_fields: dict) -> str:
+        """
+        Build a printable test header for identification of a test entry
+        :param test_fields: dict containing various test entry fields
+        :return: a formatted string containing a printable test id that can fully identify the test entry.
+        """
         test_no = test_fields.get(TEST_NO)
         lang = test_fields.get(LANGUAGE)
         cve = test_fields.get(VULN_ID)
         git = test_fields.get(GIT_REPO)
         return f'Test #{test_no}: Language={lang}, vuln_id={cve}, git_repo={git}'
 
     def build_common_test_footer(self, test_fields: dict, result_fields: dict) -> str:
+        """
+        This method crafts a string that containing the data relevant for test comparison for a given test case.
+        It takes the relevant fields from test entry and its corresponding result.
+        :param result_fields: result entry fields dictionary
+        :param test_fields: test entry fields dictionary
+        :return: a formatted script that fully describe the test result ( all relevant fields)
+        """
         (actual_result, allowed_labels, expected_label,
          justification_label, test_expected_result) = self.get_test_to_be_matched_fields(result_fields, test_fields)