From aaee444c68e5545ed2522cc330100ecbcef3eca7 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Tue, 24 Mar 2020 16:49:21 +0100 Subject: [PATCH] Document more methods in Python scripts Signed-off-by: Gilles Peskine --- tests/scripts/check-files.py | 19 +++++++++++++++++++ tests/scripts/check-test-cases.py | 2 ++ 2 files changed, 21 insertions(+) diff --git a/tests/scripts/check-files.py b/tests/scripts/check-files.py index 6e35f5224..16aebb59a 100755 --- a/tests/scripts/check-files.py +++ b/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) diff --git a/tests/scripts/check-test-cases.py b/tests/scripts/check-test-cases.py index 4abaa6882..35a998749 100755 --- a/tests/scripts/check-test-cases.py +++ b/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):