From 2b29424efd05fb059ba35f16eb804613676c869d Mon Sep 17 00:00:00 2001
From: praschke <stel@comfy.monster>
Date: Sun, 28 Nov 2021 11:28:47 +0000
Subject: [PATCH] docs: reorganize `@truncate` and `@intCast` for clarity

---
 doc/langref.html.in | 25 ++++++++++++++-----------
 1 file changed, 14 insertions(+), 11 deletions(-)

diff --git a/doc/langref.html.in b/doc/langref.html.in
index 33a93268cb..8b7e9b87e6 100644
--- a/doc/langref.html.in
+++ b/doc/langref.html.in
@@ -8537,6 +8537,16 @@ test "@hasDecl" {
       Attempting to convert a number which is out of range of the destination type results in
       safety-protected {#link|Undefined Behavior#}.
       </p>
+      {#code_begin|test_err|cast truncated bits#}
+test "integer cast panic" {
+    var a: u16 = 0xabcd;
+    var b: u8 = @intCast(u8, a);
+    _ = b;
+}
+      {#code_end#}
+      <p>
+      To truncate the significant bits of a number out of range of the destination type, use {#link|@truncate#}.
+      </p>
       <p>
       If {#syntax#}T{#endsyntax#} is {#syntax#}comptime_int{#endsyntax#},
       then this is semantically equivalent to {#link|Type Coercion#}.
@@ -9380,17 +9390,11 @@ fn List(comptime T: type) type {
       or same-sized integer type.
       </p>
       <p>
-      The following produces safety-checked {#link|Undefined Behavior#}:
+      This function always truncates the significant bits of the integer, regardless
+      of endianness on the target platform.
       </p>
-      {#code_begin|test_err|cast truncated bits#}
-test "integer cast panic" {
-    var a: u16 = 0xabcd;
-    var b: u8 = @intCast(u8, a);
-    _ = b;
-}
-      {#code_end#}
       <p>
-      However this is well defined and working code:
+      Calling {#syntax#}@truncate{#endsyntax#} on a number out of range of the destination type is well defined and working code:
       </p>
       {#code_begin|test|truncate#}
 const std = @import("std");
@@ -9403,8 +9407,7 @@ test "integer truncation" {
 }
       {#code_end#}
       <p>
-      This function always truncates the significant bits of the integer, regardless
-      of endianness on the target platform.
+      Use {#link|@intCast#} to convert numbers guaranteed to fit the destination type.
       </p>
       {#header_close#}