Document more methods in Python scripts

Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>

tests/scripts/check-files.py

@@ -37,20 +37,31 @@ class FileIssueTracker(object):
         self.files_with_issues = {}
 
     def should_check_file(self, filepath):
+        """Whether the given file name should be checked.
+
+        Files whose name ends with a string listed in ``self.files_exemptions``
+        will not be checked.
+        """
         for files_exemption in self.files_exemptions:
             if filepath.endswith(files_exemption):
                 return False
         return True
 
     def check_file_for_issue(self, filepath):
+        """Check the specified file for the issue that this class is for.
+
+        Subclasses must implement this method.
+        """
         raise NotImplementedError
 
     def record_issue(self, filepath, line_number):
+        """Record that an issue was found at the specified location."""
         if filepath not in self.files_with_issues.keys():
             self.files_with_issues[filepath] = []
         self.files_with_issues[filepath].append(line_number)
 
     def output_file_issues(self, logger):
+        """Log all the locations where the issue was found."""
         if self.files_with_issues.values():
             logger.info(self.heading)
             for filename, lines in sorted(self.files_with_issues.items()):
@@ -70,6 +81,10 @@ class LineIssueTracker(FileIssueTracker):
     """
 
     def issue_with_line(self, line, filepath):
+        """Check the specified line for the issue that this class is for.
+
+        Subclasses must implement this method.
+        """
         raise NotImplementedError
 
     def check_file_line(self, filepath, line, line_number):
@@ -77,6 +92,10 @@ class LineIssueTracker(FileIssueTracker):
             self.record_issue(filepath, line_number)
 
     def check_file_for_issue(self, filepath):
+        """Check the lines of the specified file.
+
+        Subclasses must implement the ``issue_with_line`` method.
+        """
         with open(filepath, "rb") as f:
             for i, line in enumerate(iter(f.readline, b"")):
                 self.check_file_line(filepath, line, i + 1)

tests/scripts/check-test-cases.py

@@ -77,6 +77,7 @@ def check_description(results, seen, file_name, line_number, description):
     seen[description] = line_number
 
 def check_test_suite(results, data_file_name):
+    """Check the test cases in the given unit test data file."""
     in_paragraph = False
     descriptions = {}
     with open(data_file_name, 'rb') as data_file:
@@ -94,6 +95,7 @@ def check_test_suite(results, data_file_name):
             in_paragraph = True
 
 def check_ssl_opt_sh(results, file_name):
+    """Check the test cases in ssl-opt.sh or a file with a similar format."""
     descriptions = {}
     with open(file_name, 'rb') as file_contents:
         for line_number, line in enumerate(file_contents, 1):