From 34e0197453dfbfc192a157670e473a36f3d28ebc Mon Sep 17 00:00:00 2001
From: Denis Blank <denis.blank@outlook.com>
Date: Sat, 10 Mar 2018 12:51:48 +0100
Subject: [PATCH] More work on the tutorial section

---
 doc/Doxyfile                           |  3 +-
 doc/tutorial-chaining-continuables.dox | 82 ++++++++++++++++++++------
 doc/tutorial-creating-continuables.dox | 33 ++++++++---
 doc/tutorial.dox                       |  2 -
 4 files changed, 90 insertions(+), 30 deletions(-)

diff --git a/doc/Doxyfile b/doc/Doxyfile
index 98e6034..da626db 100644
--- a/doc/Doxyfile
+++ b/doc/Doxyfile
@@ -790,7 +790,8 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = ../include
+INPUT                  = ../include \
+                         ../doc
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
diff --git a/doc/tutorial-chaining-continuables.dox b/doc/tutorial-chaining-continuables.dox
index 08db14a..83c7257 100644
--- a/doc/tutorial-chaining-continuables.dox
+++ b/doc/tutorial-chaining-continuables.dox
@@ -26,28 +26,72 @@ namespace cti {
 
 \tableofcontents
 
+\section tutorial-chaining-continuables-then Using then and results
+
+A \ref continuable_base provides various methods to continue the asynchronous
+call hierarchy. The most important method therefor is
+\ref continuable_base::then which changes the object through attaching a
+result handler:
+
+\code{.cpp}
+http_request("github.com")
+  .then([] (std::string result) {
+    // Do something...
+  });
+\endcode
+
+A new \ref continuable_base is created which result depends on the return type
+of the handler. For instance it is possible to return plain values or the next
+\ref continuable_base to continue the call hierarchy.
+See \ref continuable_base::then for details.
+
+\code{.cpp}
+mysql_query("SELECT `id`, `name` FROM `users`")
+  .then([](ResultSet users) {
+    // Return the next continuable to process ...
+    return mysql_query("SELECT `id` name FROM `sessions`");
+  })
+  .then([](ResultSet sessions) {
+    // ... or pass multiple values to the next callback using tuples or pairs ...
+    return std::make_tuple(std::move(sessions), true);
+  })
+  .then([](ResultSet sessions, bool is_ok) {
+    // ... or pass a single value to the next callback ...
+    return 10;
+  })
+  .then([](auto value) {
+    //     ^^^^ Templated callbacks are possible too
+  })
+  // ... you may even pass continuables to the `then` method directly:
+  .then(mysql_query("SELECT * `statistics`"))
+  .then([](ResultSet result) {
+    // ...
+  });
+\endcode
+
+\section tutorial-chaining-continuables-fail Using fail and errors
+
+\code{.cpp}
+http_request("github.com")
+  .then([] (std::string result) {
+    // Is never called
+  })
+  .fail([] (std::exception_ptr ptr) {
+    try {
+      std::rethrow_exception(ptr);
+    } catch(std::exception const& e) {
+      // Handle the exception or error code here
+    }
+  });
+\endcode
+
+\section tutorial-chaining-continuables-next Using next for everything
+
+
 The \ref cti::continuable_base \ref cti::when_any \ref cti::promisify
 
-- Supply a continuable which is invoked lazily upon request:
-
-
 - Continue the continuation using `.then(...)` and `.fail(...)`, exceptions are passed to the first available handler:
-  \code{.cpp}
-  http_request("github.com")
-    .then([] (std::string result) {
-      // Do something...
-      return http_request("travis-ci.org")
-    })
-    .then([] (std::string result) {
-      // Handle the response from 'travis-ci.org'
-    })
-    .fail([] (std::exception_ptr ptr) {
-      try {
-        std::rethrow_exception(ptr);
-      } catch(std::exception const& e) {
-        // Handle the exception or error code here
-      }
-    });
+
   \endcode
 
 - Create connections between the continuables and use its compound result:
diff --git a/doc/tutorial-creating-continuables.dox b/doc/tutorial-creating-continuables.dox
index 6ecb935..95ce021 100644
--- a/doc/tutorial-creating-continuables.dox
+++ b/doc/tutorial-creating-continuables.dox
@@ -34,12 +34,7 @@ know its exact type for avoiding expensive type erasure.
 The \ref continuable_base is convertible to a \ref continuable which represents
 a specified type of the \ref continuable_base on the cost of a type erasure.
 
-An asynchronous call hierarchy that is stored inside the \ref continuable_base
-is executed when its result is requested (lazy evaluation) in contrast to
-other commonly used abstractions such as `std::future` which execute the
-asynchronous call hierarchy instantly on creation (eager evaluation).
-
-\section tutorial-creating-continuables-ready From a value or exception type
+\section tutorial-creating-continuables-ready From a value or exception
 
 The library provides \ref make_ready_continuable which may be used to create a
 \ref continuable_base from an arbitrary amount of values:
@@ -84,11 +79,33 @@ auto http_request(std::string url) {
 }
 \endcode
 
-\attention After resolving a \ref promise_base it should not be used any more,
-           because the class is only usable once.
+\warning A \ref promise_base is only usable once and thus invalidated
+         after it was resolved!
 
 A \ref promise_base always exposes a call operator for resolving it as
 like when using \ref promise_base::set_value or
 \ref promise_base::set_exception. See \ref promise_base for details.
+
+\note In order to make proper use of a \ref promise_base you should
+      move it around, store it for later use and resolve it when
+      the asynchronous task was finished or rejected.
+
+\section tutorial-creating-continuables-invocation The continuable invocation model
+
+An asynchronous call hierarchy that is stored inside the \ref continuable_base
+is executed when its result is requested (lazy evaluation) in contrast to
+other commonly used abstractions such as `std::future` which execute the
+asynchronous call hierarchy instantly on creation (eager evaluation).
+
+The asynchronous call hierarchy is started when the \ref continuable_base is
+destructed or the \ref continuable_base::done method is called.
+It is possible to disable the automatic start through calling
+\ref continuable_base::freeze on the corresponding \ref continuable_base.
+
+\attention A \ref continuable_base is not designed to be stored permanently,
+           make sure you call \ref continuable_base::freeze before storing it
+           and start the continuation chain later through calling
+           \ref continuable_base::done.
+
 */
 }
diff --git a/doc/tutorial.dox b/doc/tutorial.dox
index 40ada94..9a9ab4e 100644
--- a/doc/tutorial.dox
+++ b/doc/tutorial.dox
@@ -24,8 +24,6 @@ namespace cti {
 /** \page tutorial Tutorial
 \brief An introduction for using the continuable library.
 
-\tableofcontents
-
 This tutorial will give a short overview about using the library.
 We assume that the library is available in your current environment,
 if not, follow the \ref installation section in order to get it to work.