Augment thrift.ExceptionMessage docs (#591)

Summary: Pull Request resolved: facebook/fbthrift#591

Reviewed By: thedavekwon

Differential Revision: D52861937

fbshipit-source-id: d9dc88d32f338c0ecd193242b4b93840a4783310

Author: Aristidis Papaioannou

third-party/thrift/src/thrift/annotation/thrift.thrift

@@ -167,6 +167,22 @@ struct BitmaskEnum {}
 
 /**
  * Specifies the field where the exception message is stored.
+ *
+ * The "exception message" is typically a human-readable description of the
+ * exception. It is made available to the exception-handling code via standard,
+ * language-dependent APIs of the generated code, such as:
+ *   - [`std::exception::what()`](https://en.cppreference.com/w/cpp/error/exception/what)
+ *      in C++.
+ *   - [`Throwable.getMessage()`](https://docs.oracle.com/javase/8/docs/api/java/lang/Throwable.html#getMessage--)
+ *     in Java.
+ *   - etc.
+ *
+ * This annotation can be specified on at most one field of an
+ * [exception definition](https://github.com/facebook/fbthrift/blob/main/thrift/doc/idl/index.md#exceptions),
+ * whose type must be `string`.
+ *
+ * If an exception definition does not specify this anotation for any field, the
+ * exception message returned by the aforementioned APIs is unspecified.
  */
 @scope.Field
 struct ExceptionMessage {}

third-party/thrift/src/thrift/doc/features/exception.md

@@ -13,6 +13,12 @@ A **declared** exception is an exception struct defined in IDL. Interfaces can d
 
 An **undeclared** exception is thrown by Thrift methods that are wrapped into a generic [TApplicationException](https://github.com/facebook/fbthrift/blob/main/thrift/lib/cpp/TApplicationException.h) or [TTransportException](https://github.com/facebook/fbthrift/blob/main/thrift/lib/cpp/transport/TTransportException.h) and passed to the client. It is similar to throwing generic exceptions (e.g. `Exception` or `std::exception`) and is generally discouraged since it is too general to carry sufficient information. It is highly encouraged to avoid as much as possible throwing undeclared exceptions.
 
+### Exception Message
+
+A custom (human-readable) exception message may be specified in a field, by
+annotating it with
+[`@thrift.ExceptionMessage`](/idl/annotations.md#thrift-annotations).
+
 ## Error Classification
 ### Kind
 Thrift Error can be classified into three categories: **Transient**, **Stateful**, and **Permanent**.