From e11cd2316bf752d42ab03807f40112e85cd46ab0 Mon Sep 17 00:00:00 2001
From: Andrew Kelley <andrew@ziglang.org>
Date: Thu, 27 Aug 2026 13:41:18 -0700
Subject: [PATCH] langref: IINAH (Inline Is Not A Hint)

maybe this meme will help spread the information better
---
 doc/langref.html.in | 26 ++++++++++++++++----------
 1 file changed, 16 insertions(+), 10 deletions(-)

diff --git a/doc/langref.html.in b/doc/langref.html.in
index a0ea833d85a0f16320c71a784a4fd35a8a855f1a..27e6e9723f001fcf7d8f879e3f144a1aeaa14347 100644
--- a/doc/langref.html.in
+++ b/doc/langref.html.in
@@ -2934,8 +2934,8 @@ or
       {#header_open|inline fn#}
       <p>
       Adding the {#syntax#}inline{#endsyntax#} keyword to a function definition makes that
-      function become <em>semantically inlined</em> at the callsite. This is
-      not a hint to be possibly observed by optimization passes, but has
+      function become <em>semantically inlined</em> at the callsite. {#link|Inline Is Not A Hint#}
+      to be possibly observed by optimization passes, but has
       implications on the types and values involved in the function call.
       </p>
       <p>
@@ -2947,16 +2947,22 @@ or
 
       <p>If {#syntax#}inline{#endsyntax#} is removed, the test fails with the compile error
       instead of passing.</p>
-      <p>It is generally better to let the compiler decide when to inline a
-      function, except for these scenarios:</p>
+
+      {#header_open|Inline Is Not A Hint#}
+      <p>Use of {#syntax#}inline{#endsyntax#} <em>restricts</em> what the
+      compiler is allowed to do. <strong>This can harm binary size, compilation speed,
+      and even runtime performance.</strong> In exchange, these use cases are addressed:</p>
       <ul>
-        <li>To change how many stack frames are in the call stack, for debugging purposes.</li>
-        <li>To force comptime-ness of the arguments to propagate to the return value of the function, as in the above example.</li>
-        <li>Real world performance measurements demand it.</li>
+        <li>Ability to ensure certain stack frames are in the call stack, for
+        debugging purposes, or for integrating with {#link|Assembly#}.</li>
+        <li>Forcing arguments from the callsite that happen to be
+        {#link|comptime#} to propagate to the return value of the function, as
+        in the above example.</li>
+        <li>Working around limitations of compiler backend implementations.</li>
       </ul>
-      <p>Note that {#syntax#}inline{#endsyntax#} actually <em>restricts</em>
-      what the compiler is allowed to do. This can harm binary size,
-      compilation speed, and even runtime performance.</p>
+      <p>For an alternative to {#syntax#}inline{#endsyntax#} that merely hints to the compiler
+      that inlining a function may be valuable, use {#link|@branchHint#}.</p>
+      {#header_close#}
       {#header_close#}
 
       {#header_open|Function Reflection#}
-- 
2.54.0