started to add Doxygen documentation

dietmarkuehl · dietmarkuehl · commit cc7e0749a186 · 2024-11-04T00:34:12.000Z
diff --git a/.doxy-config b/.doxy-config
diff --git a/Makefile b/Makefile
@@ -2,7 +2,7 @@
 # SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 
 SANITIZERS = release debug msan asan usan tsan
-.PHONY: default run update check ce todo distclean clean build test all format $(SANITIZERS)
+.PHONY: default doc run update check ce todo distclean clean build test all format $(SANITIZERS)
 
 COMPILER=system
 CXX_BASE=$(CXX:$(dir $(CXX))%=%)
@@ -51,6 +51,9 @@ all: $(SANITIZERS)
 run: test
 	./$(BUILD)/examples/$(EXAMPLE)
 
+doc:
+	doxygen .doxy-config
+
 release: test
 
 $(SANITIZERS):
diff --git a/docs/beman-logo.png b/docs/beman-logo.png
diff --git a/include/beman/execution26/detail/allocator_aware_move.hpp b/include/beman/execution26/detail/allocator_aware_move.hpp
@@ -14,6 +14,11 @@
 
 namespace beman::execution26::detail {
 template <typename T, typename Context>
+/*!
+ * \brief Utilitiy function use to move a possibly allocator aware object with an allocator from an environment.
+ * \headerfile beman/execution26/execution.hpp <beman/execution26/execution.hpp>
+ * \internal
+ */
 auto allocator_aware_move(T&& obj, Context&& context) -> decltype(auto) {
     if constexpr (requires { ::beman::execution26::get_allocator(::beman::execution26::get_env(context)); }) {
         if constexpr (decltype(::beman::execution26::detail::is_product_type(obj))()) {
diff --git a/include/beman/execution26/detail/almost_scheduler.hpp b/include/beman/execution26/detail/almost_scheduler.hpp
@@ -6,17 +6,19 @@
 
 #include <beman/execution26/detail/queryable.hpp>
 #include <beman/execution26/detail/schedule.hpp>
+#include <beman/execution26/detail/scheduler_t.hpp>
 #include <beman/execution26/detail/sender.hpp>
 #include <concepts>
 #include <utility>
 
 // ----------------------------------------------------------------------------
 
-namespace beman::execution26 {
-struct scheduler_t {};
-} // namespace beman::execution26
-
 namespace beman::execution26::detail {
+/*!
+ * \brief Auxiliary concept used to break cycle for scheduler concept.
+ * \headerfile beman/execution26/execution.hpp <beman/execution26/execution.hpp>
+ * \internal
+ */
 template <typename Scheduler>
 concept almost_scheduler = ::std::derived_from<typename ::std::remove_cvref_t<Scheduler>::scheduler_concept,
                                                ::beman::execution26::scheduler_t> &&
diff --git a/include/beman/execution26/detail/as_awaitable.hpp b/include/beman/execution26/detail/as_awaitable.hpp
@@ -9,6 +9,10 @@
 // ----------------------------------------------------------------------------
 
 namespace beman::execution26 {
+/*!
+ * \brief Turn an entity, e.g., a sender, into an awaitable.
+ * \headerfile beman/execution26/execution.hpp <beman/execution26/execution.hpp>
+ */
 struct as_awaitable_t {
     template <typename E, typename P>
     auto operator()(E&& e, P& p) const {
diff --git a/include/beman/execution26/detail/as_except_ptr.hpp b/include/beman/execution26/detail/as_except_ptr.hpp
@@ -14,6 +14,11 @@
 // ----------------------------------------------------------------------------
 
 namespace beman::execution26::detail {
+/*!
+ * \brief Turn an error into a suitable exception_ptr.
+ * \headerfile beman/execution26/execution.hpp <beman/execution26/execution.hpp>
+ * \internal
+ */
 template <typename Error>
 decltype(auto) as_except_ptr(Error&& error) {
     if constexpr (::std::same_as<::std::exception_ptr, ::std::decay_t<Error>>) {
diff --git a/include/beman/execution26/detail/await_result_type.hpp b/include/beman/execution26/detail/await_result_type.hpp
@@ -10,11 +10,16 @@
 // ----------------------------------------------------------------------------
 
 namespace beman::execution26::detail {
+/*!
+ * \brief Auxiliary type alias to get the result type of an awaiter.
+ * \headerfile beman/execution26/execution.hpp <beman/execution26/execution.hpp>
+ * \internal
+ */
 template <typename T, typename Promise>
 using await_result_type =
     decltype(::beman::execution26::detail::get_awaiter(::std::declval<T>(), ::std::declval<Promise&>())
                  .await_resume());
-}
+} // namespace beman::execution26::detail
 
 // ----------------------------------------------------------------------------
 
diff --git a/include/beman/execution26/detail/await_suspend_result.hpp b/include/beman/execution26/detail/await_suspend_result.hpp
@@ -11,11 +11,26 @@
 // ----------------------------------------------------------------------------
 
 namespace beman::execution26::detail {
+/*!
+ * \brief Auxiliary type trait used to detect specializations of `std::coroutine_handle`.
+ * \headerfile beman/execution26/execution.hpp <beman/execution26/execution.hpp>
+ * \internal
+ */
 template <typename>
 struct is_coroutine_handle : ::std::false_type {};
+/*!
+ * \brief The actual partial specialization detecting `std::coroutine_handle`.
+ * \headerfile beman/execution26/execution.hpp <beman/execution26/execution.hpp>
+ * \internal
+ */
 template <typename T>
 struct is_coroutine_handle<::std::coroutine_handle<T>> : ::std::true_type {};
 
+/*!
+ * \brief A concept used to identify valid results for `await_suspend`.
+ * \headerfile beman/execution26/execution.hpp <beman/execution26/execution.hpp>
+ * \internal
+ */
 template <typename T>
 concept await_suspend_result =
     ::std::same_as<T, void> || ::std::same_as<T, bool> || ::beman::execution26::detail::is_coroutine_handle<T>::value;
diff --git a/include/beman/execution26/detail/basic_operation.hpp b/include/beman/execution26/detail/basic_operation.hpp
@@ -19,6 +19,11 @@
 // ----------------------------------------------------------------------------
 
 namespace beman::execution26::detail {
+/*!
+ * \brief Class template use to factor out common operation state needs.
+ * \headerfile beman/execution26/execution.hpp <beman/execution26/execution.hpp>
+ * \internal
+ */
 template <typename Sender, typename Receiver>
     requires ::beman::execution26::detail::
         valid_specialization<::beman::execution26::detail::state_type, Sender, Receiver>
diff --git a/include/beman/execution26/detail/basic_receiver.hpp b/include/beman/execution26/detail/basic_receiver.hpp
@@ -22,6 +22,11 @@
 // ----------------------------------------------------------------------------
 
 namespace beman::execution26::detail {
+/*!
+ * \brief Class template used as receiver for child completions for library senders.
+ * \headerfile beman/execution26/execution.hpp <beman/execution26/execution.hpp>
+ * \internal
+ */
 template <typename Sender, typename Receiver, typename Index>
     requires ::beman::execution26::detail::
         valid_specialization< ::beman::execution26::detail::env_type, Index, Sender, Receiver>
diff --git a/include/beman/execution26/detail/basic_sender.hpp b/include/beman/execution26/detail/basic_sender.hpp
@@ -18,6 +18,11 @@
 // ----------------------------------------------------------------------------
 
 namespace beman::execution26::detail {
+/*!
+ * \brief Class template used to factor out common sender implementation for library senders.
+ * \headerfile beman/execution26/execution.hpp <beman/execution26/execution.hpp>
+ * \internal
+ */
 template <typename Tag, typename Data, typename... Child>
 struct basic_sender : ::beman::execution26::detail::product_type<Tag, Data, Child...> {
     friend struct ::beman::execution26::connect_t;
@@ -34,7 +39,7 @@ struct basic_sender : ::beman::execution26::detail::product_type<Tag, Data, Chil
 
   private:
     template <typename Receiver>
-        requires(not::beman::execution26::receiver<Receiver>)
+        requires(not ::beman::execution26::receiver<Receiver>)
     auto connect(Receiver receiver) = BEMAN_EXECUTION26_DELETE("the passed receiver doesn't model receiver");
 #if __cpp_explicit_this_parameter < 202110L
     template <::beman::execution26::receiver Receiver>
diff --git a/include/beman/execution26/detail/basic_state.hpp b/include/beman/execution26/detail/basic_state.hpp
@@ -13,6 +13,11 @@
 // ----------------------------------------------------------------------------
 
 namespace beman::execution26::detail {
+/*!
+ * \brief Class template used to present the receiver and operation state for library senders.
+ * \headerfile beman/execution26/execution.hpp <beman/execution26/execution.hpp>
+ * \internal
+ */
 template <typename Sender, typename Receiver>
 struct basic_state {
     basic_state(Sender&& sender, Receiver&& receiver) noexcept(true)
diff --git a/include/beman/execution26/detail/call_result_t.hpp b/include/beman/execution26/detail/call_result_t.hpp
@@ -10,6 +10,11 @@
 
 namespace beman::execution26::detail {
 template <typename Fun, typename... Args>
+/*!
+ * \brief Type alias used determine the result of function [object] call.
+ * \headerfile beman/execution26/execution.hpp <beman/execution26/execution.hpp>
+ * \internal
+ */
 using call_result_t = decltype(::std::declval<Fun>()(std::declval<Args>()...));
 }
 
diff --git a/include/beman/execution26/detail/callable.hpp b/include/beman/execution26/detail/callable.hpp
@@ -9,6 +9,11 @@
 // ----------------------------------------------------------------------------
 
 namespace beman::execution26::detail {
+/*!
+ * \brief Concept used to detect callable objects.
+ * \headerfile beman/execution26/execution.hpp <beman/execution26/execution.hpp>
+ * \internal
+ */
 template <typename Fun, typename... Args>
 concept callable = requires(Fun&& fun, Args&&... args) { ::std::forward<Fun>(fun)(::std::forward<Args>(args)...); };
 } // namespace beman::execution26::detail
diff --git a/include/beman/execution26/detail/check_type_alias_exist.hpp b/include/beman/execution26/detail/check_type_alias_exist.hpp
@@ -7,9 +7,14 @@
 // ----------------------------------------------------------------------------
 
 namespace beman::execution26::detail {
+/*!
+ * \brief Auxiliary class template used to detect whether a type alias exist within a class.
+ * \headerfile beman/execution26/execution.hpp <beman/execution26/execution.hpp>
+ * \internal
+ */
 template <template <typename> class>
 struct check_type_alias_exist;
-}
+} // namespace beman::execution26::detail
 
 // ----------------------------------------------------------------------------
 
diff --git a/include/beman/execution26/detail/child_type.hpp b/include/beman/execution26/detail/child_type.hpp
@@ -10,9 +10,14 @@
 // ----------------------------------------------------------------------------
 
 namespace beman::execution26::detail {
+/*!
+ * \brief Auxiliary type alias used to determine the type of a child sender.
+ * \headerfile beman/execution26/execution.hpp <beman/execution26/execution.hpp>
+ * \internal
+ */
 template <typename Sender, ::std::size_t I = 0u>
 using child_type = decltype(::std::declval<Sender>().template get<I + 2>());
-}
+} // namespace beman::execution26::detail
 
 // ----------------------------------------------------------------------------
 
diff --git a/include/beman/execution26/detail/common.hpp b/include/beman/execution26/detail/common.hpp
@@ -13,16 +13,31 @@
 #endif
 
 // ----------------------------------------------------------------------------
+/*!
+ * \mainpage Asynchronous Operation Support
+ *
+ * This project implements the C++ support for asynchronous operations,
+ * knows as _sender/receiver_ or `std::execution`.
+ */
 
-namespace beman::execution26::detail {
-template <typename...>
-struct fail_type;
-template <typename... T>
-auto fail(T&&...) {
-    fail_type<T...>{};
-}
-auto use(auto&&...) noexcept -> void {}
-} // namespace beman::execution26::detail
+/*!
+ * \namespace beman
+ * \brief Namespace for Beman projects http://github.com/beman-project/beman
+ * \headerfile beman/execution26/execution.hpp <beman/execution26/execution.hpp>
+ */
+namespace beman {
+/*!
+ * \namespace beman::execution26
+ * \brief Namespace for asynchronous operations and their vocabulary.
+ *
+ * \details
+ * The beman::execution26 namespace contains various components for
+ * accessing asynchronous operations.
+ *
+ * \headerfile beman/execution26/execution.hpp <beman/execution26/execution.hpp>
+ */
+namespace execution26 {}
+} // namespace beman
 
 // ----------------------------------------------------------------------------
 
diff --git a/include/beman/execution26/detail/completion_signature.hpp b/include/beman/execution26/detail/completion_signature.hpp
@@ -27,6 +27,18 @@ struct is_set_value : ::std::false_type {};
 template <typename... Args>
 struct is_set_value<::beman::execution26::set_value_t(Args...)> : ::std::true_type {};
 
+/*!
+ * \brief Detect if a type is a completion signature.
+ *
+ * \details
+ * The three completion signatures are
+ * - set_error_t(E) for completion with an error.
+ * - set_stopped_t() to indicate that operation was cancelled.
+ * - set_value_t(A...) for successful completion with a set of argument.
+ *
+ * \headerfile beman/execution26/execution.hpp <beman/execution26/execution.hpp>
+ * \internal
+ */
 template <typename Fun>
 concept completion_signature =
     ::beman::execution26::detail::is_set_error<Fun>::value ||
diff --git a/include/beman/execution26/detail/connect.hpp b/include/beman/execution26/detail/connect.hpp
@@ -14,7 +14,7 @@
 
 // ----------------------------------------------------------------------------
 
-namespace beman::execution26 {
+namespace beman::execution26::detail {
 struct connect_t {
     template <typename Sender, typename Receiver>
     auto operator()(Sender&& sender, Receiver&& receiver) const noexcept(true /*-dk:TODO*/) {
@@ -42,6 +42,13 @@ struct connect_t {
         }
     }
 };
+} // namespace beman::execution26::detail
+
+namespace beman::execution26 {
+using beman::execution26::detail::connect_t;
+/*!
+ * \brief Customization point object used to connect a sender and a receiver.
+ */
 inline constexpr connect_t connect{};
 } // namespace beman::execution26
 
diff --git a/include/beman/execution26/detail/connect_result_t.hpp b/include/beman/execution26/detail/connect_result_t.hpp
@@ -10,9 +10,13 @@
 // ----------------------------------------------------------------------------
 
 namespace beman::execution26 {
+/*!
+ * \brief Type alias to determine the operation state type returned from `connect()`.
+ * \headerfile beman/execution26/execution.hpp <beman/execution26/execution.hpp>
+ */
 template <typename Sender, typename Receiver>
 using connect_result_t = decltype(::beman::execution26::connect(::std::declval<Sender>(), ::std::declval<Receiver>()));
-}
+} // namespace beman::execution26
 
 // ----------------------------------------------------------------------------
 
diff --git a/include/beman/execution26/detail/continues_on.hpp b/include/beman/execution26/detail/continues_on.hpp
@@ -70,6 +70,10 @@ auto get_domain_late(Sender&& sender, Env&&) {
 
 namespace beman::execution26 {
 using ::beman::execution26::detail::continues_on_t;
+/*!
+ * \brief Customization point object to create a `continues_on` sender.
+ * \headerfile beman/execution26/execution.hpp <beman/execution26/execution.hpp>
+ */
 inline constexpr continues_on_t continues_on{};
 } // namespace beman::execution26
 
diff --git a/include/beman/execution26/detail/default_domain.hpp b/include/beman/execution26/detail/default_domain.hpp
@@ -14,16 +14,20 @@
 // ----------------------------------------------------------------------------
 
 namespace beman::execution26 {
+/*!
+ * \brief Domain type used when no domain is specified explicitly.
+ * \headerfile beman/execution26/execution.hpp <beman/execution26/execution.hpp>
+ */
 struct default_domain {
     template <::beman::execution26::sender Sender, ::beman::execution26::detail::queryable... Env>
         requires(sizeof...(Env) <= 1) && requires(Sender&& sender, Env&&... env) {
             ::beman::execution26::tag_of_t<Sender>().transform_sender(::std::forward<Sender>(sender),
                                                                       ::std::forward<Env>(env)...);
         }
     static constexpr auto transform_sender(Sender&& sender, Env&&... env) noexcept(
-        noexcept(::beman::execution26::tag_of_t<Sender>().transform_sender(::std::forward<Sender>(sender),
-                                                                           ::std::forward<Env>(env)...)))
-        -> ::beman::execution26::sender decltype(auto) {
+        noexcept(::beman::execution26::tag_of_t<Sender>().transform_sender(
+            ::std::forward<Sender>(sender), ::std::forward<Env>(env)...))) -> ::beman::execution26::sender
+        decltype(auto) {
         return ::beman::execution26::tag_of_t<Sender>().transform_sender(::std::forward<Sender>(sender),
                                                                          ::std::forward<Env>(env)...);
     }
@@ -33,9 +37,8 @@ struct default_domain {
                     ::beman::execution26::tag_of_t<Sender>().transform_sender(::std::forward<Sender>(sender),
                                                                               ::std::forward<Env>(env)...);
                 })
-    static constexpr auto transform_sender(Sender&& sender,
-                                           Env&&...) noexcept(noexcept(::std::forward<Sender>(sender)))
-        -> ::beman::execution26::sender decltype(auto) {
+    static constexpr auto transform_sender(Sender&& sender, Env&&...) noexcept(
+        noexcept(::std::forward<Sender>(sender))) -> ::beman::execution26::sender decltype(auto) {
         return ::std::forward<Sender>(sender);
     }
 
@@ -52,9 +55,9 @@ struct default_domain {
 
     template <::beman::execution26::sender Sender, ::beman::execution26::detail::queryable Env>
         requires(not requires(Sender&& sender, Env&& env) {
-            ::beman::execution26::tag_of_t<Sender>().transform_env(::std::forward<Sender>(sender),
-                                                                   ::std::forward<Env>(env));
-        })
+                    ::beman::execution26::tag_of_t<Sender>().transform_env(::std::forward<Sender>(sender),
+                                                                           ::std::forward<Env>(env));
+                })
     static constexpr auto transform_env(Sender&&, Env&& env) noexcept -> ::beman::execution26::detail::queryable
         decltype(auto) {
         return static_cast<Env>(::std::forward<Env>(env));
diff --git a/include/beman/execution26/detail/schedule_from.hpp b/include/beman/execution26/detail/schedule_from.hpp
diff --git a/include/beman/execution26/detail/scheduler_t.hpp b/include/beman/execution26/detail/scheduler_t.hpp
diff --git a/include/beman/execution26/detail/set_error.hpp b/include/beman/execution26/detail/set_error.hpp
diff --git a/include/beman/execution26/detail/set_stopped.hpp b/include/beman/execution26/detail/set_stopped.hpp
diff --git a/include/beman/execution26/detail/set_value.hpp b/include/beman/execution26/detail/set_value.hpp
diff --git a/tests/beman/execution26/exec-read-env.test.cpp b/tests/beman/execution26/exec-read-env.test.cpp
diff --git a/tests/beman/execution26/exec-snd-expos.test.cpp b/tests/beman/execution26/exec-snd-expos.test.cpp
