From 11ee6df95cfc720c75f5a224ea1c19a4ba0998ff Mon Sep 17 00:00:00 2001
From: whosit <knbdevel@gmail.com>
Date: Sat, 22 Mar 2025 03:41:59 +0300
Subject: [PATCH] add more comments

---
 using_xpcall.lua | 27 ++++++++++++++++++++++-----
 1 file changed, 22 insertions(+), 5 deletions(-)

diff --git a/using_xpcall.lua b/using_xpcall.lua
index c5b4897..96d656e 100644
--- a/using_xpcall.lua
+++ b/using_xpcall.lua
@@ -1,5 +1,9 @@
-local formspec_log = futil and futil.Deque and futil.Deque()
+--- This part is unrelated to pcall/xpcall usage. Scroll to "Usage
+--- example" below to see the relevant parts.
 
+
+-- use efficient deque or implement our own FIFO type of thing
+local formspec_log = futil and futil.Deque and futil.Deque()
 if not formspec_log then
     -- no deque implementation found
     local deq = {}
@@ -84,7 +88,8 @@ local function formspec_log_show(playername)
 end
 
 
-
+-- These commands will allow us to see the errors saved in
+-- the `formspec_log` after they happen.
 core.register_chatcommand(
     "debug_formspec_log_show",
     {
@@ -108,8 +113,10 @@ core.register_chatcommand(
 )
 
 
+
+--------------------------------------------------------------------------------
+---          Usage example
 --------------------------------------------------------------------------------
---- Usage example
 
 local function bugged(playername, params)
     for _=1,tonumber(params) do
@@ -119,6 +126,7 @@ local function bugged(playername, params)
 end
 
 
+-- this command will crash if you pass it wrong arguments
 core.register_chatcommand(
     "bugged",
     {
@@ -129,7 +137,12 @@ core.register_chatcommand(
     }
 )
 
+-- This is the simplest safe version using `pcall`, it will return
+-- status and error message on crash.
 
+-- This command definition does not require any of the error handling
+-- code above. The limitation is that this will only give us the error
+-- message.
 core.register_chatcommand(
     "bugged_safe",
     {
@@ -145,7 +158,10 @@ core.register_chatcommand(
     }
 )
 
-
+-- This version allows us to get the error stack trace. We get the
+-- trace by passing our helper function `error_printer` to xpcall.
+-- (`error_printer` will be called on error without unwinding the
+-- stack, so we can call `debug` functions to examine the error).
 core.register_chatcommand(
     "bugged_safe2",
     {
@@ -162,7 +178,8 @@ core.register_chatcommand(
     }
 )
 
-
+-- This is equivalent to `xpcall` safe2 version, but uses generic
+-- wrapper function we defined above.
 core.register_chatcommand(
     "bugged_safe3",
     {