From 9119cc72f6423388b1c1486a60e87cfdfedc283e Mon Sep 17 00:00:00 2001
From: Simon Brunel <simonbrunel@users.noreply.github.com>
Date: Fri, 1 Feb 2019 16:06:29 +0100
Subject: [PATCH] Add documentation for built-in exceptions

---
 docs/.vuepress/config.js               |  8 ++++++++
 docs/qtpromise/api-reference.md        |  6 ++++++
 docs/qtpromise/exceptions/canceled.md  | 19 +++++++++++++++++++
 docs/qtpromise/exceptions/timeout.md   | 18 ++++++++++++++++++
 docs/qtpromise/exceptions/undefined.md | 26 ++++++++++++++++++++++++++
 docs/qtpromise/qpromise/constructor.md |  2 +-
 docs/qtpromise/qpromise/timeout.md     |  2 +-
 7 files changed, 79 insertions(+), 2 deletions(-)
 create mode 100644 docs/qtpromise/exceptions/canceled.md
 create mode 100644 docs/qtpromise/exceptions/timeout.md
 create mode 100644 docs/qtpromise/exceptions/undefined.md

diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js
index f7b24a2..7996f50 100644
--- a/docs/.vuepress/config.js
+++ b/docs/.vuepress/config.js
@@ -52,6 +52,14 @@ module.exports = {
                     'qtpromise/helpers/qpromise',
                     'qtpromise/helpers/qpromiseall'
                 ]
+            },
+            {
+                title: 'Exceptions',
+                children: [
+                    'qtpromise/exceptions/canceled',
+                    'qtpromise/exceptions/timeout',
+                    'qtpromise/exceptions/undefined'
+                ]
             }
         ]
     }
diff --git a/docs/qtpromise/api-reference.md b/docs/qtpromise/api-reference.md
index d4112dd..02afa58 100644
--- a/docs/qtpromise/api-reference.md
+++ b/docs/qtpromise/api-reference.md
@@ -32,3 +32,9 @@
 * [`QtPromise::map`](helpers/map.md)
 * [`qPromise`](helpers/qpromise.md)
 * [`qPromiseAll`](helpers/qpromiseall.md)
+
+## Exceptions
+
+* [`QPromiseCanceledException`](exceptions/canceled.md)
+* [`QPromiseTimeoutException`](exceptions/timeout.md)
+* [`QPromiseUndefinedException`](exceptions/undefined.md)
diff --git a/docs/qtpromise/exceptions/canceled.md b/docs/qtpromise/exceptions/canceled.md
new file mode 100644
index 0000000..b42347a
--- /dev/null
+++ b/docs/qtpromise/exceptions/canceled.md
@@ -0,0 +1,19 @@
+---
+title: QPromiseCanceledException
+---
+
+# QPromiseCanceledException
+
+*Since: 0.1.0*
+
+This exception is thrown for promise created from a [`QFuture`](../qtconcurrent.md)
+which has been canceled (e.g. using [`QFuture::cancel()`](http://doc.qt.io/qt-5/qfuture.html#cancel)).
+Note that QtPromise doesn't support promise cancelation yet. For example:
+
+```cpp
+auto output = qPromise(future)
+    .fail([](const QPromiseCanceledException&) {
+        // `future` has been canceled!
+    });
+```
+
diff --git a/docs/qtpromise/exceptions/timeout.md b/docs/qtpromise/exceptions/timeout.md
new file mode 100644
index 0000000..725c2f6
--- /dev/null
+++ b/docs/qtpromise/exceptions/timeout.md
@@ -0,0 +1,18 @@
+---
+title: QPromiseTimeoutException
+---
+
+# QPromiseTimeoutException
+
+*Since: 0.2.0*
+
+This is the default exception thrown when reaching the time limit when using
+the [`QPromise::timeout()`](../qpromise/timeout.md) method, for example:
+
+```cpp
+QPromise<int> input = {...}
+auto output = input.timeout(2000)
+    .fail([](const QPromiseTimeoutException& e) {
+        // operation timed out after 2s!
+    });
+```
diff --git a/docs/qtpromise/exceptions/undefined.md b/docs/qtpromise/exceptions/undefined.md
new file mode 100644
index 0000000..fb6ecae
--- /dev/null
+++ b/docs/qtpromise/exceptions/undefined.md
@@ -0,0 +1,26 @@
+---
+title: QPromiseUndefinedException
+---
+
+# QPromiseUndefinedException
+
+*Since: 0.5.0*
+
+This exception is thrown when rejecting a promise with no explicit reason, for
+example:
+
+```cpp
+QPromise<int> promise([](const QPromiseResolve<int>& resolve, const QPromiseReject<int>& reject) {
+    async_method([=](bool success, int result) {
+        if (success) {
+            resolve(result);
+        } else {
+            reject();
+        }
+    });
+});
+
+promise.fail([](const QPromiseUndefinedException&) {
+    // promise rejected without reason!
+})
+```
diff --git a/docs/qtpromise/qpromise/constructor.md b/docs/qtpromise/qpromise/constructor.md
index 4935361..dcd8961 100644
--- a/docs/qtpromise/qpromise/constructor.md
+++ b/docs/qtpromise/qpromise/constructor.md
@@ -42,7 +42,7 @@ QPromise<int> promise([](const auto& resolve, const auto& reject) {
 
 While not recommended because it makes tracking errors more difficult, it's also
 possible to reject a promise without explicit reason, in which case, a built-in
-`QPromiseUndefinedException` is thrown:
+[`QPromiseUndefinedException`](../exceptions/undefined.md) is thrown:
 
 ```cpp
 QPromise<int> promise([](const QPromiseResolve<int>& resolve, const QPromiseReject<int>& reject) {
diff --git a/docs/qtpromise/qpromise/timeout.md b/docs/qtpromise/qpromise/timeout.md
index 3c6e00d..5549f11 100644
--- a/docs/qtpromise/qpromise/timeout.md
+++ b/docs/qtpromise/qpromise/timeout.md
@@ -10,7 +10,7 @@ title: .timeout
 QPromise<T>::timeout(int msec, any error = QPromiseTimeoutException) -> QPromise<T>
 ```
 
-This method returns a promise that will be resolved with the `input` promise's fulfillment value or rejection reason. However, if the `input` promise is not fulfilled or rejected within `msec` milliseconds, the `output` promise is rejected with `error` as the reason (`QPromiseTimeoutException` by default).
+This method returns a promise that will be resolved with the `input` promise's fulfillment value or rejection reason. However, if the `input` promise is not fulfilled or rejected within `msec` milliseconds, the `output` promise is rejected with `error` as the reason ([`QPromiseTimeoutException`](../exceptions/timeout.md) by default).
 
 ```cpp
 QPromise<int> input = {...}