From d045eb7a4af758e3483e5e8fd9bdbe725095fdec Mon Sep 17 00:00:00 2001
From: Alex Kladov <aleksey.kladov@gmail.com>
Date: Mon, 14 Jul 2025 16:12:55 +0100
Subject: [PATCH 1/3] langref: make example more interesting.

As written, I think langref's example is actually a poor reason to use
`inline`.

If you have

     if (foo(1200, 34) != 1234) {
         @compileError("bad");
     }

and you want to make sure that the call is executed at compile time, the
right way to fix it is to add comptime

     if (comptime foo(1200, 34) != 1234) {
         @compileError("bad");
     }

and not to make the function `inline`. I _think_ that inlining functions
just to avoid `comptime` at a call-site is an anti-pattern. When the
reader sees `foo(123)` at the call-site, they _expect_ this to be a
runtime call, as that's the normal rule in Zig.

Inline is still necessary when you can't make the _whole_ call
`comptime`, because it has some runtime effects, but you still want
comptime-known result.

A good example here is

    inline fn findImportPkgHashOrFatal(b: *Build, comptime asking_build_zig: type, comptime dep_name: []const u8) []const u8 {

from Build.zig, where the `b` argument is runtime, and is used for
side-effects, but where the result is comptime.

I don't know of a good small example to demonstrate the subtelty here,
so I went ahead with just adding a runtime print to `foo`. Hopefully
it'll be enough for motivated reader to appreciate the subtelty!
---
 doc/langref/inline_call.zig | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/doc/langref/inline_call.zig b/doc/langref/inline_call.zig
index a0cc1440ae..17625884bd 100644
--- a/doc/langref/inline_call.zig
+++ b/doc/langref/inline_call.zig
@@ -1,3 +1,5 @@
+const std = @import("std");
+
 test "inline function call" {
     if (foo(1200, 34) != 1234) {
         @compileError("bad");
@@ -5,6 +7,7 @@ test "inline function call" {
 }
 
 inline fn foo(a: i32, b: i32) i32 {
+    std.debug.print("runtime a = {} b = {}", .{ a, b });
     return a + b;
 }
 

From 96bb1137c23688f01283be24ac9b52e1440afded Mon Sep 17 00:00:00 2001
From: Alex Kladov <aleksey.kladov@gmail.com>
Date: Mon, 14 Jul 2025 17:32:50 +0100
Subject: [PATCH 2/3] langref: don't encourage printing to stderr in tests

The rule: `pub fn main` owns file descriptors 0, 1, and 2. If you didn't
write `pub fn main()` it is, in general, not your business to print to
stderr.
---
 doc/langref/defer_unwind.zig | 4 ++--
 doc/langref/inline_call.zig  | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/doc/langref/defer_unwind.zig b/doc/langref/defer_unwind.zig
index dfd729dc5b..ebcca130a6 100644
--- a/doc/langref/defer_unwind.zig
+++ b/doc/langref/defer_unwind.zig
@@ -2,7 +2,7 @@ const std = @import("std");
 const expect = std.testing.expect;
 const print = std.debug.print;
 
-test "defer unwinding" {
+pub fn main() void {
     print("\n", .{});
 
     defer {
@@ -19,4 +19,4 @@ test "defer unwinding" {
     }
 }
 
-// test
+// exe=succeed
diff --git a/doc/langref/inline_call.zig b/doc/langref/inline_call.zig
index 17625884bd..d1ee6a72ae 100644
--- a/doc/langref/inline_call.zig
+++ b/doc/langref/inline_call.zig
@@ -1,6 +1,6 @@
 const std = @import("std");
 
-test "inline function call" {
+pub fn main() void {
     if (foo(1200, 34) != 1234) {
         @compileError("bad");
     }
@@ -11,4 +11,4 @@ inline fn foo(a: i32, b: i32) i32 {
     return a + b;
 }
 
-// test
+// exe=succeed

From d90646d8fbd8658120c39bc2690088c0efa21157 Mon Sep 17 00:00:00 2001
From: Alex Kladov <aleksey.kladov@gmail.com>
Date: Mon, 14 Jul 2025 17:34:52 +0100
Subject: [PATCH 3/3] langref: remove dead code

---
 doc/langref/defer_unwind.zig | 1 -
 1 file changed, 1 deletion(-)

diff --git a/doc/langref/defer_unwind.zig b/doc/langref/defer_unwind.zig
index ebcca130a6..65fe11015b 100644
--- a/doc/langref/defer_unwind.zig
+++ b/doc/langref/defer_unwind.zig
@@ -1,5 +1,4 @@
 const std = @import("std");
-const expect = std.testing.expect;
 const print = std.debug.print;
 
 pub fn main() void {