Add a configuration documentation section

CMakeLists.txt

@@ -85,7 +85,7 @@ if (CTI_CONTINUABLE_WITH_AWAIT)
 
   target_compile_definitions(continuable-base
     INTERFACE
-      -DCONTINUABLE_HAS_EXPERIMENTAL_COROUTINE)
+      -DCONTINUABLE_WITH_EXPERIMENTAL_COROUTINE)
 endif()
 
 add_library(continuable INTERFACE)

doc/configuration.dox

@@ -0,0 +1,39 @@
+/*
+  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 configuration Configuration
+\brief Covers optional preprocessor macros that change the libraries behaviour
+
+By default the library doesn't require any preprocessor definitions
+to be defined in order to work. However it is possible to define some
+in order to change the libraries behaviour:
+
+| Preprocessor definition                   | Consequence     |
+| ----------------------------------------- | --------------- |
+| `CONTINUABLE_WITH_NO_EXCEPTIONS`          | Exceptions are disabled and `std::error_condition` is used as \ref error_type . See \ref tutorial-chaining-continuables-fail for details. | 
+| `CONTINUABLE_WITH_CUSTOM_ERROR_TYPE`      | Exceptions are disabled and the type defined by `CONTINUABLE_WITH_CUSTOM_ERROR_TYPE` is used as \ref error_type . See \ref tutorial-chaining-continuables-fail for details. |
+| `CONTINUABLE_WITH_UNHANDLED_EXCEPTIONS`   | Allows unhandled exceptions in asynchronous call hierarchies. See \ref tutorial-chaining-continuables-fail for details. |
+| `CONTINUABLE_WITH_EXPERIMENTAL_COROUTINE` | Enables support for experimental coroutines and `co_await` expressions. |
+
+*/
+}

doc/tutorial-chaining-continuables.dox

@@ -78,7 +78,7 @@ handler that was attached through \ref continuable_base::fail :
 \code{.cpp}
 http_request("github.com")
   .then([] (std::string result) {
-    // Is never called
+    // Is never called if an error occurs
   })
   .fail([] (std::exception_ptr ptr) {
     try {
@@ -111,29 +111,52 @@ handler below is called.
 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
+\code{.cpp}
+http_request("github.com")
+  .then([] (std::string result) {
+    // Is never called if an error occurs
+  })
+  .fail([] (std::error_condition error) {
+    error.value();
+    error.category();
+  });
+\endcode
+
+The \ref 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.
+  as \ref 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.
 
+\attention By default unhandled exceptions or errors will trigger
+           a built-in trap that causes abnormal application shutdown.
+           In order to prevent this and to allow unhandled errors
+           define `CONTINUABLE_WITH_UNHANDLED_EXCEPTIONS`.
+
 \section tutorial-chaining-continuables-next Using next for everything
 
+Sometimes it's required to provide a continuation and error handler from the
+same object. In order to avoid overloading conflicts there is the special
+method \ref continuable_base::next provided.
+The exception path overload is marked through the \ref dispatch_error_tag :
 
-The \ref cti::continuable_base \ref cti::when_any \ref cti::promisify
+\code{.cpp}
+struct handle_everything {
+  void operator() (std::string result) {
+    // ...
+  }
+  void operator() (cti::dispatch_error_tag, cti::error_type) {
+    // ...
+  }
+};
 
-- Continue the continuation using `.then(...)` and `.fail(...)`, exceptions are passed to the first available handler:
+// ...
 
-  \endcode
+http_request("github.com")
+  .next(handle_everything{});
+\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")))
-    .then([](std::string github, std::string travis_or_atom) {
-      // The promise is called with the response of github and travis or atom.
-    });
-  \endcode
 */
 }

include/continuable/continuable-base.hpp

@@ -73,7 +73,7 @@ namespace cti {
 /// \note see continuable::next for details.
 ///
 /// \since 2.0.0
-using detail::types::dispatch_error_tag;
+using dispatch_error_tag = detail::types::dispatch_error_tag;
 
 /// Represents the type that is used as error type
 ///
@@ -84,7 +84,7 @@ using detail::types::dispatch_error_tag;
 /// defining `CONTINUABLE_WITH_CUSTOM_ERROR_TYPE`.
 ///
 /// \since 2.0.0
-using detail::types::error_type;
+using error_type = detail::types::error_type;
 
 /// Deduces to a true_type if the given type is a continuable_base.
 ///

include/continuable/detail/base.hpp

@@ -457,12 +457,12 @@ struct final_callback : util::non_copyable {
 
   void operator()(types::dispatch_error_tag, types::error_type error) && {
     (void)error;
-#ifndef CONTINUABLE_WITH_UNHANDLED_ERRORS
+#ifndef CONTINUABLE_WITH_UNHANDLED_EXCEPTIONS
     // There were unhandled errors inside the asynchronous call chain!
-    // Define `CONTINUABLE_WITH_UNHANDLED_ERRORS` in order
+    // Define `CONTINUABLE_WITH_UNHANDLED_EXCEPTIONS` in order
     // to ignore unhandled errors!"
     util::trap();
-#endif // CONTINUABLE_WITH_UNHANDLED_ERRORS
+#endif // CONTINUABLE_WITH_UNHANDLED_EXCEPTIONS
   }
 
   template <typename... Args>

include/continuable/detail/features.hpp

@@ -83,6 +83,13 @@
   #define CONTINUABLE_HAS_EXPERIMENTAL_COROUTINE
 #endif
 
+/// Define CONTINUABLE_HAS_EXPERIMENTAL_COROUTINE when
+/// CONTINUABLE_WITH_EXPERIMENTAL_COROUTINE is defined.
+#if !defined(CONTINUABLE_HAS_EXPERIMENTAL_COROUTINE) &&                            \
+    defined(CONTINUABLE_WITH_EXPERIMENTAL_COROUTINE)
+  #define CONTINUABLE_HAS_EXPERIMENTAL_COROUTINE
+#endif
+
 /// Define CONTINUABLE_HAS_EXCEPTIONS when exceptions are used
 #if !defined(CONTINUABLE_WITH_CUSTOM_ERROR_TYPE) &&                            \
     !defined(CONTINUABLE_WITH_NO_EXCEPTIONS)