More work on the tutorial

doc/installation.dox

@@ -0,0 +1,30 @@
+/*
+  Copyright(c) 2015 - 2018 Denis Blank <denis.blank at outlook dot com>
+
+  Permission is hereby granted, free of charge, to any person obtaining a copy
+  of this software and associated documentation files(the "Software"), to deal
+  in the Software without restriction, including without limitation the rights
+  to use, copy, modify, merge, publish, distribute, sublicense, and / or sell
+  copies of the Software, and to permit persons to whom the Software is
+  furnished to do so, subject to the following conditions :
+
+  The above copyright notice and this permission notice shall be included in
+  all copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.IN NO EVENT SHALL THE
+  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+  SOFTWARE.
+*/
+
+namespace cti {
+/** \page installation Installation
+\brief An explanation on how to install continuable on various platforms.
+
+\tableofcontents
+
+*/
+}

doc/tutorial-chaining-continuables.dox

@@ -63,13 +63,17 @@ mysql_query("SELECT `id`, `name` FROM `users`")
     //     ^^^^ Templated callbacks are possible too
   })
   // ... you may even pass continuables to the `then` method directly:
-  .then(mysql_query("SELECT * `statistics`"))
+  .then(mysql_query("SELECT * FROM `statistics`"))
   .then([](ResultSet result) {
     // ...
   });
 \endcode
 
-\section tutorial-chaining-continuables-fail Using fail and errors
+\section tutorial-chaining-continuables-fail Using fail and exceptions
+
+Asynchronous exceptions are supported too. Exceptions that were set through
+\ref promise_base::set_exception are forwarded to the first available registered
+handler that was attached through \ref continuable_base::fail :
 
 \code{.cpp}
 http_request("github.com")
@@ -85,6 +89,36 @@ http_request("github.com")
   });
 \endcode
 
+Multiple handlers are allowed to be registered, however the asynchronous call
+hierarchy is aborted after the first called fail handler and only the closest
+handler below is called.
+
+\note Retrieving a `std::exception_ptr` from a current exception
+      may be done as shown below:
+  \code{.cpp}
+  auto do_sth() {
+    return cti::make_continuable<void>([=] (auto&& promise) {
+      try {
+        // Usually the exception is thrown by another expression
+        throw std::exception{};
+      } catch(...) {
+        promise.set_exception(std::current_exception());
+      }
+    });
+  }
+  \endcode
+
+Continuable also supports error codes automatically if exceptions are disabled.
+Additionally it is possible to specify a custom error type through defining.
+
+The \ref cti::error_type will be `std::exception_ptr` except if any of the
+following definitions is defined:
+- `CONTINUABLE_WITH_NO_EXCEPTIONS`: Define this to use `std::error_condition`
+  as \ref cti::error_type and to disable exception support.
+  When exceptions are disabled this definition is set automatically.
+- `CONTINUABLE_WITH_CUSTOM_ERROR_TYPE`:  Define this to use a user defined
+  error type.
+
 \section tutorial-chaining-continuables-next Using next for everything
 
 

doc/tutorial-creating-continuables.dox

@@ -40,7 +40,10 @@ The library provides \ref make_ready_continuable which may be used to create a
 \ref continuable_base from an arbitrary amount of values:
 
 \code{.cpp}
-cti::continuable<int> c = cti::make_ready_continuable(0);
+auto one = cti::make_ready_continuable(0);
+
+cti::continuable<int, float, char> three =
+  cti::make_ready_continuable(0, 1.f, '2');
 \endcode
 
 \note In most situations you will never use \ref make_ready_continuable
@@ -79,6 +82,28 @@ auto http_request(std::string url) {
 }
 \endcode
 
+An alternative would be a \ref continuable_base with a result of zero arguments:
+
+\code{.cpp}
+auto wait_for(std::chrono::milliseconds duration) {
+  return cti::make_continuable<void>([](auto&& promise) {
+  //                           ^^^^
+
+  // Resolve the promise later when the duration is over
+  promise.set_value();
+});
+\endcode
+
+A \ref continuable_base may resolve with an arbitrary count of result values:
+
+\code{.cpp}
+auto resolve_sth() {
+  return cti::make_continuable<int, int, float, char>(
+    [](auto&& promise) {
+      promise.set_value(0, 1, 2.f, '3');
+  });
+\endcode
+
 \warning A \ref promise_base is only usable once and thus invalidated
          after it was resolved!