abi_check.py: Document more methods

scripts/abi_check.py

@@ -26,8 +26,16 @@ import tempfile
 
 
 class AbiChecker(object):
+    """API and ABI checker."""
 
     def __init__(self, report_dir, old_rev, new_rev, keep_all_reports):
+        """Instantiate the API/ABI checker.
+
+        report_dir: directory for output files
+        old_rev: reference git revision to compare against
+        new_rev: git revision to check
+        keep_all_reports: if false, delete old reports
+        """
         self.repo_path = "."
         self.log = None
         self.setup_logger()
@@ -42,7 +50,8 @@ class AbiChecker(object):
         self.git_command = "git"
         self.make_command = "make"
 
-    def check_repo_path(self):
+    @staticmethod
+    def check_repo_path():
         current_dir = os.path.realpath('.')
         root_dir = os.path.dirname(os.path.dirname(os.path.realpath(__file__)))
         if current_dir != root_dir:
@@ -53,12 +62,15 @@ class AbiChecker(object):
         self.log.setLevel(logging.INFO)
         self.log.addHandler(logging.StreamHandler())
 
-    def check_abi_tools_are_installed(self):
+    @staticmethod
+    def check_abi_tools_are_installed():
         for command in ["abi-dumper", "abi-compliance-checker"]:
             if not shutil.which(command):
                 raise Exception("{} not installed, aborting".format(command))
 
     def get_clean_worktree_for_git_revision(self, git_rev):
+        """Make a separate worktree with git_rev checked out.
+        Do not modify the current worktree."""
         self.log.info(
             "Checking out git worktree for revision {}".format(git_rev)
         )
@@ -88,6 +100,7 @@ class AbiChecker(object):
             raise Exception("git submodule update failed, aborting")
 
     def build_shared_libraries(self, git_worktree_path):
+        """Build the shared libraries in the specified worktree."""
         my_environment = os.environ.copy()
         my_environment["CFLAGS"] = "-g -Og"
         my_environment["SHARED"] = "1"
@@ -104,6 +117,9 @@ class AbiChecker(object):
             raise Exception("make failed, aborting")
 
     def get_abi_dumps_from_shared_libraries(self, git_ref, git_worktree_path):
+        """Generate the ABI dumps for the specified git revision.
+        It must be checked out in git_worktree_path and the shared libraries
+        must have been built."""
         abi_dumps = {}
         for mbed_module in self.mbedtls_modules:
             output_path = os.path.join(
@@ -129,6 +145,7 @@ class AbiChecker(object):
         return abi_dumps
 
     def cleanup_worktree(self, git_worktree_path):
+        """Remove the specified git worktree."""
         shutil.rmtree(git_worktree_path)
         worktree_process = subprocess.Popen(
             [self.git_command, "worktree", "prune"],
@@ -142,6 +159,7 @@ class AbiChecker(object):
             raise Exception("Worktree cleanup failed, aborting")
 
     def get_abi_dump_for_ref(self, git_rev):
+        """Generate the ABI dumps for the specified git revision."""
         git_worktree_path = self.get_clean_worktree_for_git_revision(git_rev)
         self.update_git_submodules(git_worktree_path)
         self.build_shared_libraries(git_worktree_path)
@@ -152,6 +170,9 @@ class AbiChecker(object):
         return abi_dumps
 
     def get_abi_compatibility_report(self):
+        """Generate a report of the differences between the reference ABI
+        and the new ABI. ABI dumps from self.old_rev and self.new_rev must
+        be available."""
         compatibility_report = ""
         compliance_return_code = 0
         for mbed_module in self.mbedtls_modules:
@@ -201,6 +222,8 @@ class AbiChecker(object):
         return compliance_return_code
 
     def check_for_abi_changes(self):
+        """Generate a report of ABI differences
+        between self.old_rev and self.new_rev."""
         self.check_repo_path()
         self.check_abi_tools_are_installed()
         self.old_dumps = self.get_abi_dump_for_ref(self.old_rev)