diff --git a/doc/.gitignore b/doc/.gitignore deleted file mode 100644 index 94f90d1..0000000 --- a/doc/.gitignore +++ /dev/null @@ -1 +0,0 @@ -doxygen/ diff --git a/doc/doxygen/Doxyfile b/doc/doxygen/Doxyfile index 8fe3903..a798841 100644 --- a/doc/doxygen/Doxyfile +++ b/doc/doxygen/Doxyfile @@ -38,13 +38,13 @@ PROJECT_NAME = Continuable # could be handy for archiving the generated documentation or if some version # control system is used. -PROJECT_NUMBER = +PROJECT_NUMBER = 3.0.0 # Using the PROJECT_BRIEF tag one can provide an optional one line description # for a project that appears at the top of each page and should give viewer a # quick idea about the purpose of the project. Keep the description short. -PROJECT_BRIEF = "C++14 allocation aware futures (supporting then, error handling, co_await and compositions)" +PROJECT_BRIEF = # With the PROJECT_LOGO tag one can specify a logo or an icon that is included # in the documentation. The maximum height of the logo should not exceed 55 diff --git a/include/continuable/continuable-base.hpp b/include/continuable/continuable-base.hpp index 64b0360..6c39626 100644 --- a/include/continuable/continuable-base.hpp +++ b/include/continuable/continuable-base.hpp @@ -47,6 +47,10 @@ #include namespace cti { +/// \defgroup Base Base +/// provides classes and functions to create continuable_base objects. +/// \{ + /// Represents a tag which can be placed first in a signature /// in order to overload callables with the asynchronous result /// as well as an error. @@ -105,8 +109,7 @@ using detail::base::is_continuable; /// \note Nearly all methods of the cti::continuable_base are required to be /// called as r-value. This is required because the continuable carries /// variables which are consumed when the object is transformed as part -/// of a method call. You may copy a continuable which underlying -/// storages are copyable to split the call hierarchy into multiple parts. +/// of a method call. /// /// \attention The continuable_base objects aren't intended to be stored. /// If you want to store a continuble_base you should always @@ -612,12 +615,12 @@ public: /// \cond false #ifdef CONTINUABLE_HAS_EXPERIMENTAL_COROUTINE /// \endcond - /// Implements the operator for awaiting on continuables using co_await. + /// Implements the operator for awaiting on continuables using `co_await`. /// /// The operator is only enabled if `CONTINUABLE_HAS_EXPERIMENTAL_COROUTINE` /// is defined and the toolchain supports experimental coroutines. /// - /// The return type of the co_await expression is specified as following: + /// The return type of the `co_await` expression is specified as following: /// | Continuation type | co_await returns | /// | : ------------------------------- | : -------------------------------- | /// | `continuable_base with <>` | `void` | @@ -702,20 +705,20 @@ private: } }; -/// Creates a continuable_base from a callback taking function. +/// Creates a continuable_base from a promise/callback taking function. /// -/// \tparam Args The types (signature hint) the given callback is called with. -/// * **Some arguments** indicate the types the callback will be invoked with. +/// \tparam Args The types (signature hint) the given promise is resolved with. +/// * **Some arguments** indicate the types the promise will be invoked with. /// ```cpp -/// auto ct = cti::make_continuable([](auto&& callback) { -/// std::forward(callback)(200, "..."); +/// auto ct = cti::make_continuable([](auto&& promise) { +/// promise.set_value(200, "..."); /// }); /// ``` -/// * **void as argument** indicates that the callback will be invoked +/// * `void` **as argument** indicates that the promise will be invoked /// with no arguments: /// ```cpp -/// auto ct = cti::make_continuable([](auto&& callback) { -/// std::forward(callback)(); +/// auto ct = cti::make_continuable([](auto&& promise) { +/// promise.set_value(); /// }); /// ``` /// * **No arguments** Since version 3.0.0 make_continuable always requires @@ -726,13 +729,13 @@ private: /// the continuable right after creation. /// ```cpp /// // This won't work because the arguments are missing: -/// auto ct = cti::make_continuable([](auto&& callback) { -/// std::forward(callback)(0.f, 'c'); +/// auto ct = cti::make_continuable([](auto&& promise) { +/// promise.set_value(0.f, 'c'); /// }); /// /// // However, you are allowed to do this: -/// continuable ct = [](auto&& callback) { -/// std::forward(callback)(0.f, 'c'); +/// cti::continuable ct = [](auto&& promise) { +/// promise.set_value(callback)(0.f, 'c'); /// }; /// ``` /// @@ -772,13 +775,19 @@ private: /// }); /// ``` /// -/// \returns A continuable_base with unknown template parameters which +/// \returns A continuable_base with unspecified template parameters which /// wraps the given continuation. /// In order to convert the continuable_base to a known type -/// you need to apply type erasure. +/// you need to apply type erasure through the +/// \link cti::continuable continuable\endlink or +/// \link cti::promise promise\endlink facilities. /// -/// \note You should always turn the callback into a r-value if possible +/// \note You should always turn the callback/promise into a r-value if possible /// (`std::move` or `std::forward`) for qualifier correct invokation. +/// Additionally it's important to know that all continuable promises +/// are callbacks and just expose their call operator nicely through +/// \link cti::promise_base::set_value set_value \endlink and +/// \link cti::promise_base::set_exception set_exception \endlink. /// /// \since 1.0.0 template @@ -860,6 +869,7 @@ constexpr auto make_exceptional_continuable(Exception&& exception) { std::move(exception)); }); } +/// \} } // namespace cti #endif // CONTINUABLE_BASE_HPP_INCLUDED diff --git a/include/continuable/continuable-compositions.hpp b/include/continuable/continuable-compositions.hpp index bc72e4f..3128a03 100644 --- a/include/continuable/continuable-compositions.hpp +++ b/include/continuable/continuable-compositions.hpp @@ -43,6 +43,11 @@ #include namespace cti { +/// \defgroup Compositioning Compositions +/// provides functions to connect \link continuable_base +/// continuable_bases\endlink through various strategies. +/// \{ + /// Connects the given arguments with an all logic. /// All continuables contained inside the given nested pack are /// invoked at once. On completion the final handler is called @@ -251,7 +256,7 @@ auto when_any(Iterator begin, Iterator end) { /// Populates a homogeneous container from the given arguments. /// All arguments need to be convertible to the first one, -/// by default std::vector is used as container type. +/// by default `std::vector` is used as container type. /// /// This method mainly helps to create a homogeneous container from /// a runtime known count of continuables which type isn't exactly known. @@ -291,6 +296,7 @@ populate(First&& first, Args&&... args) { 0, ((void)container.emplace_back(std::forward(args)), 0)...}; return container; // RVO } +/// \} } // namespace cti #endif // CONTINUABLE_COMPOSITIONS_HPP_INCLUDED diff --git a/include/continuable/continuable-promise-base.hpp b/include/continuable/continuable-promise-base.hpp index 7a661df..9d1eb5a 100644 --- a/include/continuable/continuable-promise-base.hpp +++ b/include/continuable/continuable-promise-base.hpp @@ -39,6 +39,10 @@ #include namespace cti { +/// \defgroup Base Base +/// provides classes and functions to create continuable_base objects. +/// \{ + /// The promise_base makes it possible to resolve an asynchronous /// continuable through it's result or through an error type. /// @@ -110,6 +114,7 @@ public: std::move(data_)(detail::types::dispatch_error_tag{}, std::move(exception)); } }; +/// \} } // namespace cti #endif // CONTINUABLE_PROMISE_BASE_HPP_INCLUDED diff --git a/include/continuable/continuable-promisify.hpp b/include/continuable/continuable-promisify.hpp index a230f64..86b6c29 100644 --- a/include/continuable/continuable-promisify.hpp +++ b/include/continuable/continuable-promisify.hpp @@ -37,6 +37,11 @@ #include namespace cti { +/// \defgroup Promisify Promisify +/// provides helper methods to convert various callback styles to +/// \link continuable_base continuable_bases\endlink. +/// \{ + /// Helper class for converting callback taking callable types into a /// a continuable. Various styles are supported. /// - `from_asio`: Converts callback taking callable types into continuables @@ -81,6 +86,7 @@ public: std::forward(callable), std::forward(args)...); } }; +/// \} } // namespace cti #endif // CONTINUABLE_PROMISIFY_HPP_INCLUDED diff --git a/include/continuable/continuable-testing.hpp b/include/continuable/continuable-testing.hpp index 0d0bafe..fee5ebb 100644 --- a/include/continuable/continuable-testing.hpp +++ b/include/continuable/continuable-testing.hpp @@ -34,6 +34,11 @@ #include #include +/// \defgroup Testing Testing +/// provides macro shortcuts for testing asynchronous continuations through +/// GTest. +/// \{ + /// Asserts that the final callback of the given continuable was called /// with any result. /// @@ -162,4 +167,6 @@ ASSERT_ASYNC_BINARY_EXCEPTION_VALIDATION( \ cti::detail::testing::asserting_eq_check(), __VA_ARGS__) +//// \} + #endif // CONTINUABLE_TESTING_HPP_INCLUDED diff --git a/include/continuable/continuable-trait.hpp b/include/continuable/continuable-trait.hpp index 087b463..ec88c5d 100644 --- a/include/continuable/continuable-trait.hpp +++ b/include/continuable/continuable-trait.hpp @@ -39,6 +39,11 @@ #include namespace cti { +/// \defgroup Types Types +/// provides the \link cti::continuable continuable\endlink and \link +/// cti::promise promise\endlink facility for type erasure. +/// \{ + /// Trait to retrieve a continuable_base type with a given type-erasure backend. /// /// Every object may me used as type-erasure backend as long as the @@ -69,6 +74,7 @@ public: continuable_base, detail::hints::signature_hint_tag>; }; +/// \} } // namespace cti #endif // CONTINUABLE_TRAIT_HPP_INCLUDED diff --git a/include/continuable/continuable-transforms.hpp b/include/continuable/continuable-transforms.hpp index 987afe4..06f835f 100644 --- a/include/continuable/continuable-transforms.hpp +++ b/include/continuable/continuable-transforms.hpp @@ -35,6 +35,10 @@ #include namespace cti { +/// \defgroup Transforms Transforms +/// provides utilities to convert \link continuable_base continuable_bases\endlink to other types (`std::future`). +/// \{ + /// A callable tag object which marks a wrapped callable object /// as continuable transformation which enables some useful overloads. /// @@ -96,6 +100,7 @@ inline auto flatten() { return std::forward(continuable).fail([](auto&&) {}); }); } +/// \} } // namespace transforms } // namespace cti diff --git a/include/continuable/continuable-traverse-async.hpp b/include/continuable/continuable-traverse-async.hpp index 550748f..92ef38a 100644 --- a/include/continuable/continuable-traverse-async.hpp +++ b/include/continuable/continuable-traverse-async.hpp @@ -36,6 +36,10 @@ #include namespace cti { +/// \defgroup Traversal Traversal +/// provides functions to traverse and remap nested packs. +/// \{ + /// A tag which is passed to the `operator()` of the visitor /// if an element is visited synchronously. /// @@ -118,6 +122,7 @@ auto traverse_pack_async(Visitor&& visitor, T&&... pack) { return detail::traversal::apply_pack_transform_async( std::forward(visitor), std::forward(pack)...); } +/// \} } // namespace cti #endif // CONTINUABLE_TRAVERSE_ASYNC_HPP_INCLUDED diff --git a/include/continuable/continuable-traverse.hpp b/include/continuable/continuable-traverse.hpp index f16e7a6..457e6a4 100644 --- a/include/continuable/continuable-traverse.hpp +++ b/include/continuable/continuable-traverse.hpp @@ -38,6 +38,10 @@ #include namespace cti { +/// \defgroup Traversal Traversal +/// provides functions to traverse and remap nested packs. +/// \{ + /// Maps the pack with the given mapper. /// /// This function tries to visit all plain elements which may be wrapped in: @@ -106,6 +110,7 @@ void traverse_pack(Mapper&& mapper, T&&... pack) { std::forward(mapper), std::forward(pack)...); } +/// \} } // namespace cti #endif // CONTINUABLE_TRAVERSE_HPP_INCLUDED diff --git a/include/continuable/continuable-types.hpp b/include/continuable/continuable-types.hpp index b138b4d..fc2f23c 100644 --- a/include/continuable/continuable-types.hpp +++ b/include/continuable/continuable-types.hpp @@ -38,6 +38,11 @@ #include namespace cti { +/// \defgroup Types Types +/// provides the \link cti::continuable continuable\endlink and \link +/// cti::promise promise\endlink facility for type erasure. +/// \{ + // clang-format off namespace detail { /// A function which isn't size adjusted and move only @@ -80,6 +85,7 @@ using promise = typename detail::unique_trait_of< // TODO sink // clang-format on +/// \} } // namespace cti #endif // CONTINUABLE_TYPES_HPP_INCLUDED