doc: update the defer{} section, describe defer(fn){} (#25669)

spytheman · web-flow · commit ff3f12eece69 · 2025-11-05T14:32:11.000+02:00
diff --git a/doc/docs.md b/doc/docs.md
@@ -2301,25 +2301,27 @@ The above code prints:
 
 ### Defer
 
-A defer statement defers the execution of a block of statements
-until the surrounding function returns.
+A `defer {}` statement, defers the execution of the block of statements
+until the surrounding scope of the defer ends. It is a convenient feature
+that allows you to group related actions (getting access to a resource
+and cleaning/freeing it after you are done) closely together, instead
+of spreading them across multiple potentially very remote lines of code.
 
 ```v
 import os
 
-fn read_log() {
+fn read_log() ! {
 	mut ok := false
-	mut f := os.open('log.txt') or { panic(err) }
-	defer {
-		f.close()
-	}
+	mut f := os.open('log.txt')!
+	defer { f.close() }
 	// ...
 	if !ok {
+		// ...
 		// defer statement will be called here, the file will be closed
 		return
 	}
 	// ...
-	// defer statement will be called here, the file will be closed
+	// defer statement will be called here too, the file will be closed
 }
 ```
 
@@ -2402,6 +2404,52 @@ fn (mut app App) auth_with_user_middleware() (bool, string) {
 }
 ```
 
+#### defer in loop scopes:
+Defer can be used inside loops too, and the deferred statement will be executed once for each
+iteration. You can also have multiple defer statements in the same scope, in which case, they
+will be executed in reverse order of their appearance in the source code:
+```v
+fn main() {
+	defer { println('Program finish.') }
+	println('Loop start.')
+	for i in 1 .. 4 {
+		defer { println('Deferred execution for ${i}. Defer 1.') }
+		defer { println('Deferred execution for ${i}. Defer 2.') }
+		defer { println('Deferred execution for ${i}. Defer 3.') }
+		println('Loop iteration: ${i}')
+	}
+	println('Loop done.')
+}
+```
+
+The example will print this:
+```txt
+Loop start.
+Loop iteration: 1
+Deferred execution for 1. Defer 3.
+Deferred execution for 1. Defer 2.
+Deferred execution for 1. Defer 1.
+Loop iteration: 2
+Deferred execution for 2. Defer 3.
+Deferred execution for 2. Defer 2.
+Deferred execution for 2. Defer 1.
+Loop iteration: 3
+Deferred execution for 3. Defer 3.
+Deferred execution for 3. Defer 2.
+Deferred execution for 3. Defer 1.
+Loop done.
+Program finish.
+```
+
+#### defer(fn) {}
+
+Note, that in most of the examples above, the `defer{}` statement was directly inside
+a function scope, so it was executed when the function itself returned. Sometimes, you
+need to defer a statement to execute right at the function end (like the above), even
+if you are inside an inner scope (deep inside an `if` or `for`).
+
+For these more rare cases, you can use: `defer(fn) {}` instead of just `defer {}`.
+
 ### Goto
 
 V allows unconditionally jumping to a label with `goto`. The label name must be contained
