From 2674d225aa1a3501d8b32d7e3adf7e2b5c219dbd Mon Sep 17 00:00:00 2001
From: Nick Treleaven <ntrel002@gmail.com>
Date: Sun, 8 Dec 2024 06:32:57 +0000
Subject: [PATCH] [core.builtins] Improve docs for trap, likely, unlikely
 (#17491)

Based on: https://github.com/dlang/dmd/edit/master/changelog/druntime.expect-trap.dd
---
 druntime/src/core/builtins.d | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/druntime/src/core/builtins.d b/druntime/src/core/builtins.d
index 22cb42591617..f5e837ee6a9b 100644
--- a/druntime/src/core/builtins.d
+++ b/druntime/src/core/builtins.d
@@ -78,6 +78,8 @@ else version (DigitalMars)
         return val;
     }
 
+    /// Execute target dependent trap instruction, if supported.
+    /// Otherwise, abort execution.
     pragma(inline, true)
     void trap()
     {
@@ -90,7 +92,8 @@ else version (DigitalMars)
     }
 }
 
-/// Provide static branch hints
+/// Provide static branch and value hints for the LDC/GDC compilers.
+/// DMD ignores these hints.
 pragma(inline, true) bool likely(bool b)   { return expect(b, true);  }
-///
+/// ditto
 pragma(inline, true) bool unlikely(bool b) { return expect(b, false); }