diff --git a/scripts/generate_psa_constants.py b/scripts/generate_psa_constants.py
index a76bf7e..997bd3c 100755
--- a/scripts/generate_psa_constants.py
+++ b/scripts/generate_psa_constants.py
@@ -1,4 +1,11 @@
 #!/usr/bin/env python3
+
+"""Generate programs/psa/psa_constant_names_generated.c
+which is included by programs/psa/psa_constant_names.c.
+The code generated by this module is only meant to be used in the context
+of that program.
+"""
+
 import os
 import re
 import sys
@@ -179,6 +186,12 @@
 '''
 
 class MacroCollector:
+    """Collect PSA crypto macro definitions from C header files.
+
+1. Call `read_file` on the input header file(s).
+2. Call `write_file` to write ``psa_constant_names_generated.c``.
+"""
+
     def __init__(self):
         self.statuses = set()
         self.key_types = set()
@@ -198,6 +211,10 @@
     definition_re = re.compile(r'\s*#\s*define\s+(\w+)(?:\s+|\((\w+)\)\s*)(.+)(?:/[*/])?')
 
     def read_line(self, line):
+        """Parse a C header line and record the PSA identifier it defines if any.
+        This function analyzes lines that start with "#define PSA_"
+        (up to non-significant whitespace) and skips all non-matching lines."""
+        # pylint: disable=too-many-branches
         m = re.match(self.definition_re, line)
         if not m:
             return