docs: add Google-style docstrings and literal programming comments to compiler core

code/code_gen/code_gen.py

@@ -24,9 +24,19 @@ args = parser.parse_args()
 
 
 class VersionInfo(object):
+    """Encapsulates build and version metadata for the code generator execution.
+
+    This class queries the current Git repository state to fetch the HEAD commit
+    hash and checks if there are uncommitted changes, appending metadata to
+    identify the exact codebase state used to generate the output files.
+    """
 
     def __init__(self, input_raw):
+        """Initializes VersionInfo with build date, git hash, and terms metadata.
 
+        Args:
+            input_raw (str): The raw input string containing DSL term definitions.
+        """
         bd = 'build date: {}'
         bb = 'build base: {}'
 
@@ -55,15 +65,26 @@ class VersionInfo(object):
         self.term_info = tinfo.format(input_raw)
 
     def fparams(self):
+        """Formats the collected build parameters into a single string.
+
+        Returns:
+            str: Multi-line string summarizing build date, revision, and terms details.
+        """
         return "\n".join([self.build_date, self.build_base, self.off_base, self.term_info])
 
 
-
 def compile_terms(terms_raw):
-    """Parses DSL terms spec and runs it through compiler stages 1-4.
+    """Parses DSL terms spec and runs it through the four compiler stages.
+
+    This function initializes a new `CompilationContext` and executes the compiler pipeline
+    sequentially: parsing, derivative/fluctuation expansion, data dependency resolution,
+    and SymPy optimization (including buffer pooling).
+
+    Args:
+        terms_raw (str): The raw string contents of the DSL terms specification input file.
 
     Returns:
-        ctx (CompilationContext): The compiled context.
+        CompilationContext: The fully compiled and optimized compilation context.
     """
     ctx = CompilationContext()
     ParserStage().execute(terms_raw, ctx)
@@ -74,7 +95,14 @@ def compile_terms(terms_raw):
 
 
 def get_latex_equations_str(ctx):
-    """Generates the LaTeX equations dictionary string from the context."""
+    """Generates the LaTeX equations dictionary string from the context.
+
+    Args:
+        ctx (CompilationContext): The compiled context containing the averaged fields.
+
+    Returns:
+        str: A formatted string representing a Python dictionary mapping field names to LaTeX code.
+    """
     latex_lines = ["{"]
     for avg in ctx.averaged.values():
         latex_lines.append('  "{}" : r"${}$",'.format(avg.name, avg.latex))
@@ -88,6 +116,11 @@ def test(terms_raw, report=False, latex=False):
     This compiles the Lark AST through all 4 pipeline stages
     and outputs the resulting Fortran source code via FortranProgramWriter,
     a LaTeX equation dictionary via LatexWriter, or an IR report via ReportWriter.
+
+    Args:
+        terms_raw (str): The raw string contents of the DSL terms specification.
+        report (bool, optional): If True, prints a JSON-based compilation IR report instead. Defaults to False.
+        latex (bool, optional): If True, prints LaTeX equation dictionary instead. Defaults to False.
     """
     ctx = compile_terms(terms_raw)
 
@@ -99,9 +132,18 @@ def test(terms_raw, report=False, latex=False):
         FortranProgramWriter().write(ctx)
 
 
-
 def escape_fortran_string(s):
-    """Escapes string content for standard Fortran source formatting."""
+    """Escapes string content for standard Fortran source formatting.
+
+    Converts internal double quotes into double-double quotes and splits the string lines,
+    wrapping them in Fortran concatenation syntax `// char(10) // &` to respect line length limit.
+
+    Args:
+        s (str): The raw string to escape.
+
+    Returns:
+        str: The escaped and formatted Fortran string parameter literal.
+    """
     escaped = s.replace('"', '""')
     lines = escaped.splitlines()
     if not lines:
@@ -111,7 +153,14 @@ def escape_fortran_string(s):
 
 
 def generate_build_info_module(terms_raw):
-    """Generates a complete standard Fortran module containing build info and LaTeX equations."""
+    """Generates a complete standard Fortran module containing build info and LaTeX equations.
+
+    The generated module contains metadata about the compiler run, including the build base Git hash,
+    and a string representations of the LaTeX equations.
+
+    Args:
+        terms_raw (str): The raw string contents of the DSL terms specification input file.
+    """
     vinfo = VersionInfo(terms_raw)
     build_info_str = vinfo.fparams()