Specify usable escape sequences in Exception#detailed_message

An error message is primarily rendered in a terminal emulator, but is
also shown in a browser by converting it to a HTML fragment.
However, the conversion would be unreasonably difficult if the message
includes any escape sequence (such as cursor move or screen clear).

This change adds a guideline about escape sequences in
`Exception#detailed_message`:

* Use widely-supported escape sequences: bold, underline, and basic
  eight foreground colors (except white and black).
* Make the message readable if all escape sequences are ignored.

1 files changed, 22 insertions, 0 deletions

diff --git a/error.c b/error.c
index d5721b2eca..0de21aaee9 100644
--- a/error.c
+++ b/error.c
@@ -1385,6 +1385,28 @@ exc_message(VALUE exc)
  *
  * This method is overridden by did_you_mean and error_highlight to add
  * their information.
+ *
+ * A user-defined exception class can also define their own
+ * +detailed_message+ method to add supplemental information.
+ * When +highlight+ is true, it can return a string containing escape
+ * sequences, but use widely-supported ones. It is recommended to limit
+ * the following codes:
+ *
+ * - Reset (+\e[0m+)
+ * - Bold (+\e[1m+)
+ * - Underline (+\e[4m+)
+ * - Foreground color except white and black
+ *   - Red (+\e[31m+)
+ *   - Green (+\e[32m+)
+ *   - Yellow (+\e[33m+)
+ *   - Blue (+\e[34m+)
+ *   - Magenta (+\e[35m+)
+ *   - Cyan (+\e[36m+)
+ *
+ * Use escape sequeunces carefully even if +highlight+ is true.
+ * Do not use escape sequences to express essential information;
+ * the message should be readable even if all escape sequences are
+ * ignored.
  */
 
 static VALUE