chore: docs

lee/state_machine/core/src/program/mod.rs

@@ -489,6 +489,7 @@ pub struct ProgramOutput {
     pub block_validity_window: BlockValidityWindow,
     /// The timestamp window where the program output is valid.
     pub timestamp_validity_window: TimestampValidityWindow,
+    /// A vector of event data.
     pub events: Vec<Vec<u8>>,
 }
 
@@ -577,10 +578,13 @@ impl ProgramOutput {
     }
 }
 
+/// A struct holding an event-output of a program.
 #[cfg(feature = "host")]
 #[derive(Debug, Clone, PartialEq, Eq, BorshSerialize, BorshDeserialize)]
 pub struct Event {
+    // Which program emitted the event.
     pub program_id: ProgramId,
+    // The arbitrary event-data emitted in the program output.
     pub data: Vec<u8>,
 }
 

lee/state_machine/src/state/tests/mod.rs

@@ -181,8 +181,6 @@ enum FlashSwapInstruction {
     },
 }
 
-// ── Event emitter type (mirror of the guest type for host-side serialisation) ──
-
 #[derive(serde::Serialize, serde::Deserialize)]
 struct EmitterInstruction {
     events: Vec<Vec<u8>>,

lee/state_machine/src/validated_state_diff/mod.rs

@@ -262,6 +262,8 @@ impl ValidatedStateDiff {
                 state_diff.insert(pre.account_id, post.account().clone());
             }
 
+            // Write all the output event data into a proper event struct,
+            // marking its emitter program.
             events.extend(program_output.events.into_iter().map(|data| Event {
                 program_id: chained_call.program_id,
                 data,

lee/state_machine/test_methods/guest/src/bin/event_emitter.rs

@@ -35,6 +35,8 @@ fn main() {
         })
         .collect();
 
+    // Emit both the chained calls and a list of events.
+    // This is used to test the end-positioning of events in a transaction.
     ProgramOutput::new(
         self_program_id,
         caller_program_id,