more docs

hbvm/src/vm/mod.rs

@@ -124,8 +124,7 @@ impl<'a, T: HandleTrap> Vm<'a, T> {
 
     /// Execute program
     ///
-    /// Program returns [`HaltReason`] which is either [`HaltReason::ProgramEnd`] in case
+    /// Program can return [`VmRunError`] if a trap handling failed
-    /// of sucessful VM run or other in case of unhandled trap.
     pub fn run(&mut self) -> Result<(), VmRunError> {
         use hbbytecode::opcode::*;
         loop {

hbvm/src/vm/trap.rs

@@ -3,6 +3,7 @@ use super::{
     value::Value,
 };
 
+/// Handle VM traps
 pub trait HandleTrap {
     /// Handle page fault
     fn page_fault(&mut self, memory: &mut Memory, addr: u64, size: PageSize, dst: *mut u8) -> bool;

hbvm/src/vm/value.rs

@@ -1,7 +1,13 @@
 use core::fmt::Debug;
 
+/// Define [`Value`] union
+///
+/// # Safety
+/// Union variants have to be sound to byte-reinterpretate
+/// between each other. Otherwise the behaviour is undefined.
 macro_rules! value_def {
     ($($ty:ident),* $(,)?) => {
+        /// HBVM register value
         #[derive(Copy, Clone)]
         #[repr(packed)]
         pub union Value {
@@ -10,6 +16,7 @@ macro_rules! value_def {
 
         paste::paste! {
             impl Value {$(
+                #[doc = "Byte-reinterpret [`Value`] as [`" $ty "`]"]
                 #[inline]
                 pub fn [<as_ $ty>](&self) -> $ty {
                     unsafe { self.$ty }
@@ -29,9 +36,11 @@ macro_rules! value_def {
 }
 
 value_def!(u64, i64, f64);
+static_assertions::const_assert_eq!(core::mem::size_of::<Value>(), 8);
 
 impl Debug for Value {
     fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
-        self.as_u64().fmt(f)
+        // Print formatted as hexadecimal, unsigned integer
+        write!(f, "{:x}", self.as_u64())
     }
 }