More work on the tutorial section

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

doc/tutorial-chaining-continuables.dox

@@ -26,20 +26,55 @@ namespace cti {
 
 \tableofcontents
 
-The \ref cti::continuable_base \ref cti::when_any \ref cti::promisify
+\section tutorial-chaining-continuables-then Using then and results
 
-- Supply a continuable which is invoked lazily upon request:
+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:
 
-
-- 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")
+  });
+\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) {
-      // Handle the response from 'travis-ci.org'
+    // Is never called
   })
   .fail([] (std::exception_ptr ptr) {
     try {
@@ -50,6 +85,15 @@ The \ref cti::continuable_base \ref cti::when_any \ref cti::promisify
   });
 \endcode
 
+\section tutorial-chaining-continuables-next Using next for everything
+
+
+The \ref cti::continuable_base \ref cti::when_any \ref cti::promisify
+
+- Continue the continuation using `.then(...)` and `.fail(...)`, exceptions are passed to the first available handler:
+
+  \endcode
+
 - Create connections between the continuables and use its compound result:
   \code{.cpp}
   (http_request("github.com") && (http_request("travis-ci.org") || http_request("atom.io")))

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.
+
 */
 }

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.