From 6356b7dd248b703e6afa7aa9a6b0f4e771fb586c Mon Sep 17 00:00:00 2001
From: Erin <erin@erindesu.cz>
Date: Fri, 23 Jun 2023 23:55:41 +0200
Subject: [PATCH] more docs

---
 hbvm/src/vm/mod.rs   |  3 +--
 hbvm/src/vm/trap.rs  |  1 +
 hbvm/src/vm/value.rs | 11 ++++++++++-
 3 files changed, 12 insertions(+), 3 deletions(-)

diff --git a/hbvm/src/vm/mod.rs b/hbvm/src/vm/mod.rs
index 69926723..2e83b962 100644
--- a/hbvm/src/vm/mod.rs
+++ b/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
-    /// of sucessful VM run or other in case of unhandled trap.
+    /// Program can return [`VmRunError`] if a trap handling failed
     pub fn run(&mut self) -> Result<(), VmRunError> {
         use hbbytecode::opcode::*;
         loop {
diff --git a/hbvm/src/vm/trap.rs b/hbvm/src/vm/trap.rs
index 80f8ca95..c12a5f68 100644
--- a/hbvm/src/vm/trap.rs
+++ b/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;
diff --git a/hbvm/src/vm/value.rs b/hbvm/src/vm/value.rs
index cfb73005..d5738257 100644
--- a/hbvm/src/vm/value.rs
+++ b/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())
     }
 }