From 6cad447eca21ea5f4b54d09f066e1d906dc3575a Mon Sep 17 00:00:00 2001
From: Quinton Miller <nicetas.c@gmail.com>
Date: Fri, 21 Mar 2025 08:50:17 +0800
Subject: [PATCH] Document `::debugger`

---
 src/intrinsics.cr | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/src/intrinsics.cr b/src/intrinsics.cr
index 3ccc47996e0b..05c89a47f4c2 100644
--- a/src/intrinsics.cr
+++ b/src/intrinsics.cr
@@ -373,6 +373,15 @@ module Intrinsics
   end
 end
 
+# Invokes an execution trap to catch the attention of a debugger. This has the
+# same effect as placing a breakpoint in debuggers or IDEs supporting them.
+#
+# Execution is allowed to continue if the debugger instructs so. If no debugger
+# is attached, usually the current process terminates with a status that
+# corresponds to `Process::ExitReason::Breakpoint`.
+#
+# Inside an interpreter session, this drops into the REPL's pry mode instead of
+# a system debugger.
 macro debugger
   ::Intrinsics.debugtrap
 end