From b99e468c848ff8ea82b36e56c23c0ccb78481997 Mon Sep 17 00:00:00 2001
From: Dmitriy Purgin <dpurgin@gmail.com>
Date: Tue, 18 Feb 2020 22:31:41 +0100
Subject: [PATCH] More verbose description of throwing an exception from a
 QtConcurrent thread (#31)

---
 docs/qtpromise/getting-started.md |  3 +++
 docs/qtpromise/qtconcurrent.md    | 19 +++++++++++++++++--
 2 files changed, 20 insertions(+), 2 deletions(-)

diff --git a/docs/qtpromise/getting-started.md b/docs/qtpromise/getting-started.md
index 30593dc..d536711 100644
--- a/docs/qtpromise/getting-started.md
+++ b/docs/qtpromise/getting-started.md
@@ -206,3 +206,6 @@ download(url).then(&uncompress).then([](const Entries& entries) {
     // {...} catch all
 });
 ```
+
+Note that `MalformedException` in the example above is thrown from a QtConcurrent thread and should 
+meet [specific conditions](qtconcurrent.md#error).
diff --git a/docs/qtpromise/qtconcurrent.md b/docs/qtpromise/qtconcurrent.md
index b1453a1..0c81e6a 100644
--- a/docs/qtpromise/qtconcurrent.md
+++ b/docs/qtpromise/qtconcurrent.md
@@ -50,12 +50,27 @@ The `output` promise is resolved when the `QFuture` is [finished](https://doc.qt
 ## Error
 
 Exceptions thrown from a QtConcurrent thread reject the associated promise with the exception as the
-reason. Note that if you throw an exception that is not a subclass of `QException`, the promise will
+reason. For this to work, the exception should be a [`QException`](https://doc.qt.io/qt-5/qexception.html) 
+or its subclass. Correct subclassing of [`QException`](https://doc.qt.io/qt-5/qexception.html) 
+includes overriding its methods [`clone()`](https://doc.qt.io/qt-5/qexception.html#clone) and 
+[`raise()`](https://doc.qt.io/qt-5/qexception.html#raise). Without these overrides the promise will 
+be rejected with [`QException`](https://doc.qt.io/qt-5/qexception.html). 
+
+Note that if you throw an exception that is not a subclass of `QException`, the promise will
 be rejected with [`QUnhandledException`](https://doc.qt.io/qt-5/qunhandledexception.html#details)
 (this restriction only applies to exceptions thrown from a QtConcurrent thread,
-[read more](https://doc.qt.io/qt-5/qexception.html#details)).
+[read more](https://doc.qt.io/qt-5/qexception.html#details)). 
 
 ```cpp
+class CustomException : public QException
+{
+public:
+    void raise() const override { throw *this; }
+    CustomException* clone() const override { return new CustomException{*this}; }
+};
+
+// {...}
+
 QPromise<int> promise = ...
 promise.then([](int res) {
     return QtConcurrent::run([]() {