From c6cc2d2facd4e88d9e6054e495bfb596bdcfe8cb Mon Sep 17 00:00:00 2001
From: Felipe Pena <felipensp@gmail.com>
Date: Sun, 18 Feb 2024 14:39:20 -0300
Subject: [PATCH] docs: update v.debug docs - callstack+trace (#20854)

---
 doc/docs.md | 79 ++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 78 insertions(+), 1 deletion(-)

diff --git a/doc/docs.md b/doc/docs.md
index 290076a6dc..52adbdbb90 100644
--- a/doc/docs.md
+++ b/doc/docs.md
@@ -178,6 +178,8 @@ by using any of the following commands in a terminal:
         * [Compile time types](#compile-time-types)
         * [Environment specific files](#environment-specific-files)
 	* [Debugger](#debugger)
+ 		* [Call stack](#call-stack)
+   		* [Trace](#trace)
     * [Memory-unsafe code](#memory-unsafe-code)
     * [Structs with reference fields](#structs-with-reference-fields)
     * [sizeof and __offsetof](#sizeof-and-__offsetof)
@@ -6255,6 +6257,81 @@ You can also see memory usage with `mem` or `memory` command, and
 check if the current context is an anon function (`anon?`), a method (`method?`) 
 or a generic method (`generic?`) and clear the terminal window (`clear`).
 
+## Call stack
+
+You can also show the current call stack with `v.debug`.
+
+To enable this feature, add the `-d callstack` switch when building or running
+your code:
+
+```v
+import v.debug
+
+fn test(i int) {
+	if i > 9 {
+		debug.dump_callstack()
+	}
+}
+
+fn do_something() {
+	for i := 0; i <= 10; i++ {
+		test(i)
+	}
+}
+
+fn main() {
+	do_something()
+}
+```
+
+```
+$ v -d callstack run example.v
+Backtrace:
+--------------------------------------------------
+example.v:16   | > main.main
+example.v:11   |  > main.do_something
+example.v:5    |   > main.test
+--------------------------------------------------
+```
+
+## Trace
+
+Another feature of `v.debug` is the possibility to add hook functions 
+before and after each function call.
+
+To enable this feature, add the `-d trace` switch when building or running
+your code:
+
+```v
+import v.debug
+
+fn main() {
+	hook1 := debug.add_before_call(fn (fn_name string) {
+		println('> before ${fn_name}')
+	})
+	hook2 := debug.add_after_call(fn (fn_name string) {
+		println('> after ${fn_name}')
+	})
+	anon := fn () {
+		println('call')
+	}
+	anon()
+
+	// optionally you can remove the hooks:
+	debug.remove_before_call(hook1)
+	debug.remove_after_call(hook2)
+	anon()
+}
+```
+
+```
+$ v -d trace run example.v
+> before anon
+call
+> after anon
+call
+```
+
 ## Memory-unsafe code
 
 Sometimes for efficiency you may want to write low-level code that can potentially
@@ -7546,4 +7623,4 @@ Assignment Operators
 +=   -=   *=   /=   %=
 &=   |=   ^=
 >>=  <<=  >>>=
-```
\ No newline at end of file
+```