From dd567c3f6194a5c532fe9ea48913cef6e9f090b8 Mon Sep 17 00:00:00 2001
From: SANDEEP25 <sandeep.yd951@gmail.com>
Date: Fri, 7 Nov 2025 20:14:04 +0530
Subject: [PATCH] docs(hello_blockchain): add beginner-friendly comments to
 Move example

---
 .../sources/hello_blockchain.move             | 44 ++++++++++++++++---
 1 file changed, 38 insertions(+), 6 deletions(-)

diff --git a/aptos-move/move-examples/hello_blockchain/sources/hello_blockchain.move b/aptos-move/move-examples/hello_blockchain/sources/hello_blockchain.move
index 355d049697847..13b904514ce62 100644
--- a/aptos-move/move-examples/hello_blockchain/sources/hello_blockchain.move
+++ b/aptos-move/move-examples/hello_blockchain/sources/hello_blockchain.move
@@ -6,12 +6,18 @@ module hello_blockchain::message {
     #[test_only]
     use std::debug;
 
-    //:!:>resource
+    //
+    // Each account that uses this module will store one MessageHolder.
+    // This resource permanently lives under the user's account address.
+    //
     struct MessageHolder has key {
         message: string::String,
     }
-    //<:!:resource
 
+    //
+    // This event will be emitted whenever a message is changed.
+    // Events allow off-chain systems (indexers / wallets / UIs) to track updates.
+    //
     #[event]
     struct MessageChange has drop, store {
         account: address,
@@ -19,43 +25,69 @@ module hello_blockchain::message {
         to_message: string::String,
     }
 
-    /// There is no message present
+    // Error code used when trying to read a message that doesn't exist.
     const ENO_MESSAGE: u64 = 0;
 
+    //
+    // View function: returns the stored message for an account.
+    // Does NOT modify storage.
+    //
     #[view]
     public fun get_message(addr: address): string::String acquires MessageHolder {
+        // Ensure the user has initialized their message.
         assert!(exists<MessageHolder>(addr), error::not_found(ENO_MESSAGE));
+
+        // Return the current stored message.
         borrow_global<MessageHolder>(addr).message
     }
 
+    //
+    // Main function to create or update a message.
+    // Called by users via transaction.
+    //
     public entry fun set_message(account: signer, message: string::String)
     acquires MessageHolder {
+
+        // Get the address of the signer (sender of transaction).
         let account_addr = signer::address_of(&account);
+
+        // If this is the first time user interacts → create MessageHolder.
         if (!exists<MessageHolder>(account_addr)) {
-            move_to(&account, MessageHolder {
-                message,
-            })
+            move_to(&account, MessageHolder { message })
         } else {
+            // Borrow the existing message and update it.
             let old_message_holder = borrow_global_mut<MessageHolder>(account_addr);
             let from_message = old_message_holder.message;
+
+            // Emit event so off-chain systems can detect the update.
             event::emit(MessageChange {
                 account: account_addr,
                 from_message,
                 to_message: copy message,
             });
+
+            // Write the new message.
             old_message_holder.message = message;
         }
     }
 
+    //
+    // Unit test that runs only in Move testing environment.
+    //
     #[test(account = @0x1)]
     public entry fun sender_can_set_message(account: signer) acquires MessageHolder {
         let msg: string::String = string::utf8(b"Running test for sender_can_set_message...");
         debug::print(&msg);
 
         let addr = signer::address_of(&account);
+
+        // Create the testing account
         aptos_framework::account::create_account_for_test(addr);
+
+        // Call the entry function
         set_message(account, string::utf8(b"Hello, Blockchain"));
 
+        // Verify the expected result
         assert!(
             get_message(addr) == string::utf8(b"Hello, Blockchain"),
             ENO_MESSAGE