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

@@ -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();

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