From bfe4d0eb3310d5c73e9fe61b485bc91864e4c487 Mon Sep 17 00:00:00 2001
From: Charles Oliver Nutter <headius@headius.com>
Date: Mon, 6 Nov 2023 16:03:40 -0600
Subject: [PATCH] Add doco about exception prep in constructors

These methods that bottom out in `newRaiseException` or
`toThrowable` prepare the exception for an immediate throw, which
means:

* The backtrace will be populated
* The cause will be set to the currently in-flight exception
* The current thread's $! error info will be set to this exception

As such it should not be used to create a "simple" Ruby Exception
object for throwing on a different thread or at a later time.
---
 core/src/main/java/org/jruby/Ruby.java            | 15 ++++++++++++++-
 .../java/org/jruby/exceptions/RaiseException.java | 10 ++++++++++
 2 files changed, 24 insertions(+), 1 deletion(-)

diff --git a/core/src/main/java/org/jruby/Ruby.java b/core/src/main/java/org/jruby/Ruby.java
index 4736f50fb18..43a8910d1cf 100644
--- a/core/src/main/java/org/jruby/Ruby.java
+++ b/core/src/main/java/org/jruby/Ruby.java
@@ -4209,6 +4209,16 @@ public RaiseException newSystemExit(int status, String message) {
         return RubySystemExit.newInstance(this, status, message).toThrowable();
     }
 
+    /**
+     * Prepare a throwable IOError with the given message.
+     *
+     * This constructor should not be used to create a RubyException object to be raised on a different thread.
+     *
+     * @see RaiseException#from(Ruby, RubyClass, String)
+     *
+     * @param message the message for the new IOError
+     * @return a fully-prepared IOError throwable
+     */
     public RaiseException newIOError(String message) {
         return newRaiseException(getIOError(), message);
     }
@@ -4312,10 +4322,13 @@ public RaiseException newBufferMaskError(String message) {
      *
      * There are additional forms of this construction logic in {@link RaiseException#from}.
      *
+     * This constructor should not be used to create a RubyException object to be raised on a different thread.
+     *
+     * @see RaiseException#from(Ruby, RubyClass, String)
+     *
      * @param exceptionClass the exception class from which to construct the exception object
      * @param message a simple message for the exception
      * @return a new RaiseException wrapping a new Ruby exception
-     * @see RaiseException#from(Ruby, RubyClass, String)
      */
     public RaiseException newRaiseException(RubyClass exceptionClass, String message) {
         IRubyObject cause = getCurrentContext().getErrorInfo();
diff --git a/core/src/main/java/org/jruby/exceptions/RaiseException.java b/core/src/main/java/org/jruby/exceptions/RaiseException.java
index 9b3979365e6..fd8fb26f465 100644
--- a/core/src/main/java/org/jruby/exceptions/RaiseException.java
+++ b/core/src/main/java/org/jruby/exceptions/RaiseException.java
@@ -75,6 +75,16 @@ public final Throwable fillInStackTrace() {
     /**
      * Construct a new throwable RaiseException appropriate for the target Ruby exception class.
      *
+     * Note that this will produce a RaiseException that has fully prepared for being thrown, including:
+     *
+     * <ul>
+     *     <li>Populating the stack trace based on the current thread</li>
+     *     <li>Setting the cause to any currently in-flight exception</li>
+     *     <li>Setting the thread-local $! "error info" to this exception</li>
+     * </ul>
+     *
+     * This constructor should not be used to create a RubyException object to be raised on a different thread.
+     *
      * @param runtime the current JRuby runtime
      * @param exceptionClass the class of the exception to construct and raise
      * @param msg a simple message for the exception