various documentation improvements

Author: Walnut356

src/etc/lldb_batchmode/common.py

@@ -1,4 +1,5 @@
-# Contains the class definitions outlining the schema of the test data
+"""Contains the class definitions outlining the schema of the test data. For LLDB conversion
+from/into these types, see `./from_lldb.py`"""
 
 import enum
 import json
@@ -78,7 +79,7 @@ def from_dict(ty: type[Any], data: JsonType):
     """Translates a dictionary into an instance of the given dataclass type (with possibly nested
     dataclasses).
 
-    Relies on accurate type hints for the dataclass's fields, and the standard `dataclass.__init__`
+    Relies on accurate type hints for the dataclass's fields, and the default `dataclass.__init__`
     definition."""
 
     # Optional isn't a constructor, so we have to "unwrap" it.
@@ -295,19 +296,31 @@ def initialize() -> "TargetData":
         return result
 
     def save_blessing(self, metadata: BlessMetadata):
-        """Writes the entirety of `self` to the input file. Used to finalize changes made by
-        one or more `TestData.bless_variable` calls."""
+        """Writes the entirety of `self` to the env var `LLDB_BATCHMODE_INPUT_DATA_PATH`, which is
+        set by `compiletest` before running `lldb_batchmode. Used to finalize changes made by one or
+        more `from_lldb.bless_variable` calls.
+
+        This function should be called exactly once, right before
+        `lldb_batchmode.runner.main` exits if the following conditions are met:
+
+        1. No other exceptions or error states occurred
+        2. `BLESS == True`
+        3. At least one `repr` pseudo-command was processed
+
+        This prevents us from saving incomplete data or invalid data. It also prevents us from
+        creating input data files for tests that do not need it.
+        """
 
         self.bless_metadata = metadata
         path = os.environ["LLDB_BATCHMODE_INPUT_DATA_PATH"]
-        # dumping directly to a file is somewhat unsafe. If the json ends up malformed, we could
-        # end up overwriting valid test data with a complete mess. Since the in-memory data
-        # typically *isn't* malformed, the `--bless` will pass and make it seem like nothing is
-        # wrong.
+        # dumping directly to a file is somewhat unsafe. If the `Variable`/`Type` data ends up in a
+        # state that cannot be serialized correctly, the json ends up malformed, and we could end up
+        # overwriting valid test data with a complete mess. Since the in-memory data is typically
+        # completely valid, the testing logic will pass and make it seem like nothing is wrong.
 
         # While we could rely on git to help revert the test file, it's better to just not allow it
-        # to save malformed json in the first place. Thus, we dump the JSON, re-read it, and then
-        # only when that succeeds do we save it.
+        # to save malformed json in the first place. Thus, we dump the JSON, re-read it to check
+        # for `JSONDecodeError`, and write it to the target file if no error occurred.
         x = json.dumps(asdict(self), indent=" ")
         _ = json.loads(x)
 

src/etc/lldb_batchmode/from_lldb.py

@@ -1,5 +1,12 @@
-# Contains LLDB conversion functions from LLDB's in-memory representations to the test classes
-# defined in `.common`
+"""Contains LLDB conversion functions from LLDB's in-memory representations to the test classes
+defined in `./common.py`.
+
+We primarily interface with the following LLDB classes:
+
+* [`SBValue`](https://lldb.llvm.org/python_api/lldb.SBValue.html)
+* [`SBType`](https://lldb.llvm.org/python_api/lldb.SBType.html)
+* [`SBTypeMember`](https://lldb.llvm.org/python_api/lldb.SBTypeMember.html)
+"""
 
 from struct import unpack, calcsize
 
@@ -118,6 +125,7 @@ def get_summary_or_value(valobj: lldb.SBValue) -> str | None:
     want any printable representation at all, so this function falls back to `SBValue.GetValue`.
     That covers things like primitives and flat enums that typically don't have summary providers.
     """
+
     summary = valobj.GetSummary()
     if summary is None:
         return valobj.GetValue()
@@ -130,6 +138,22 @@ def field_from_lldb(field: lldb.SBTypeMember) -> Field:
 
 
 def get_generics(ty: lldb.SBType, sbtarget: lldb.SBTarget) -> list[lldb.SBType]:
+    """Platform-agnostic equivalent to `SBType.template_args`. `SBType`'s template functions do not
+    work correctly with PDB debug info because PDB has no way to represent template parameters.
+
+    Due to the DWARF spec using
+    C++-centric terminology (e.g. `DW_TAG_template_type_parameter`), the following terms are
+    interchangable:
+
+    * template type param/arg <-> generic param
+    * template value param/arg <-> const generic param
+
+    The difference between "param" and "arg" is largely irrelevant for our purposes.
+    Pre-parameterized types (e.g. `Vec<T>`, which could be parameterized to `Vec<u8>`, LLDB calls
+    this "template specialization") are not reflected in the DWARF data at all, and are largely an
+    LLDB/clang implementation detail that isn't directly exposed to us.
+    """
+
     name = ty.GetName()
     # FIXME Rust doesn't output template *values* (the `10` in `ArrayVec<u8, 10>`), only
     # template args (the `u8` in `ArrayVec<u8, 10>`). That means these can possibly have
@@ -232,10 +256,11 @@ def variable_from_lldb(var: lldb.SBValue) -> Variable:
 def bless_variable(
     target_data: TargetData, var_name: str, breakpoint_idx: int, frame: lldb.SBFrame
 ):
-    """Updates the mapping with data generated from the given variable. Only affects the mapping
-    of the current target and breakpoint. This function **does not** write to the input file.
-    Update all necessary vars, then write the entire input data at once using
-    `TestData.save_blessing`"""
+    """Updates the given `TargetData` with data generated from the given variable at the given
+    breakpoint. This function **does not** write to the input file. Please see
+    `TargetData.save_blessing` for more info on when and how to save the data.
+    """
+
     valobj = frame.FindVariable(var_name)
     if not valobj.IsValid():
         # FIXME (todo) error handling