From 85fcc086b82a4d40db6067afeff353f5880ee8f1 Mon Sep 17 00:00:00 2001
From: Ben FrantzDale <benfrantzdale@gmail.com>
Date: Wed, 9 Oct 2024 08:04:21 -0400
Subject: [PATCH 1/8] Add doxy comments to some of the metafunctions with
 breadcrumbs back to MAINTAINERS.md.

---
 include/stdexec/__detail/__meta.hpp | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/include/stdexec/__detail/__meta.hpp b/include/stdexec/__detail/__meta.hpp
index ddd5d9ef2..2ab262043 100644
--- a/include/stdexec/__detail/__meta.hpp
+++ b/include/stdexec/__detail/__meta.hpp
@@ -28,6 +28,9 @@
 #include "__utility.hpp"
 
 namespace stdexec {
+  //! Convenience metafunction getting the dependant type `__t` out of `_Tp`.
+  //! That is, `typename _Tp::__t`.
+  //! See MAINTAINERS.md#class-template-parameters for details.
   template <class _Tp>
   using __t = typename _Tp::__t;
 
@@ -373,6 +376,9 @@ namespace stdexec {
     typename __i<_Ok<_Args...>>    //
     ::template __g<_Fn, _Args...>; //
 
+  //! Metafunction invocation
+  //! Given a metafunction, `_Fn`, and args.
+  //! We expect `_Fn::__f` to be type alias template "implementing" the metafunction `_Fn`.
   template <class _Fn, class... _Args>
   using __minvoke =                       //
     typename __i<_Ok<_Args...>, _Ok<_Fn>> //
@@ -818,9 +824,13 @@ namespace stdexec {
   template <class _Default>
   using __msingle_or = __mbind_front_q<__msingle_or_, _Default>;
 
+  //! A concept checking if `_Ty` has a dependent type `_Ty::__id`.
+  //! See MAINTAINERS.md#class-template-parameters.
   template <class _Ty>
   concept __has_id = requires { typename _Ty::__id; };
 
+  //! Identity mapping `_Ty` to itself.
+  //! That is, `std::is_same_v<T, typename _Id<T>::__t>`.
   template <class _Ty>
   struct _Id {
     using __t = _Ty;
@@ -833,6 +843,7 @@ namespace stdexec {
     //static_assert(!__has_id<std::remove_cvref_t<_Ty>>);
   };
 
+  //! Helper metafunction detail of `__id`, below.
   template <bool = true>
   struct __id_ {
     template <class _Ty>
@@ -845,6 +856,10 @@ namespace stdexec {
     using __f = _Id<_Ty>;
   };
 
+  //! Metafunction mapping `_Ty` to either
+  //! * `typename _Ty::__id` if that exists, or to 
+  //! * `_Ty` (itself) otherwise.
+  //! See MAINTAINERS.md#class-template-parameters.
   template <class _Ty>
   using __id = __minvoke<__id_<__has_id<_Ty>>, _Ty>;
 

From 7ea1f5ece78b71a1d0172089f9be1ec72f048fbe Mon Sep 17 00:00:00 2001
From: Ben FrantzDale <benfrantzdale@gmail.com>
Date: Wed, 9 Oct 2024 09:38:55 -0400
Subject: [PATCH 2/8] Add comments to particularly `let_*` and `starts_on`,
 among others.

---
 include/stdexec/__detail/__basic_sender.hpp |  7 +++++++
 include/stdexec/__detail/__domain.hpp       |  5 +++++
 include/stdexec/__detail/__let.hpp          | 17 +++++++++++++++++
 include/stdexec/__detail/__meta.hpp         | 10 ++++++++++
 include/stdexec/__detail/__starts_on.hpp    |  2 ++
 5 files changed, 41 insertions(+)

diff --git a/include/stdexec/__detail/__basic_sender.hpp b/include/stdexec/__detail/__basic_sender.hpp
index 8811ed840..965264534 100644
--- a/include/stdexec/__detail/__basic_sender.hpp
+++ b/include/stdexec/__detail/__basic_sender.hpp
@@ -504,14 +504,18 @@ namespace stdexec {
   // __basic_sender
   template <class...>
   struct __basic_sender {
+    // See MAINTAINERS.md#class-template-parameters for `__id` and `__t`.
     using __id = __basic_sender;
     using __t = __basic_sender;
   };
 
+  //! A struct template to aid in creating senders.
+  //! A `__sexpr<Desc>` 
   template <auto _DescriptorFn, class = __anon>
   struct __sexpr {
     using sender_concept = sender_t;
 
+    // See MAINTAINERS.md#class-template-parameters for `__id` and `__t`.
     using __id = __sexpr;
     using __t = __sexpr;
     using __desc_t = decltype(_DescriptorFn());
@@ -595,6 +599,9 @@ namespace stdexec {
 
   //////////////////////////////////////////////////////////////////////////////////////////////////
   // __make_sexpr
+  //! A tagged function-object
+  //! Takes data and children and 
+  //! returns `__sexpr_t<_Tag, _Data, _Child...>{_Tag(), data, children...}`.
   namespace __detail {
     template <class _Tag>
     struct __make_sexpr_t {
diff --git a/include/stdexec/__detail/__domain.hpp b/include/stdexec/__detail/__domain.hpp
index ec42d30e7..1448a5d2d 100644
--- a/include/stdexec/__detail/__domain.hpp
+++ b/include/stdexec/__detail/__domain.hpp
@@ -197,6 +197,11 @@ namespace stdexec {
   } // namespace __detail
 
   /////////////////////////////////////////////////////////////////////////////
+  //! Function object implementing `get-domain-early(snd)`
+  //! from [exec.snd.general] item 3.9. It is the first well-formed expression of
+  //! a) `get_domain(get_env(sndr))`
+  //! b) `completion-domain(sndr)`
+  //! c) `default_domain()`
   inline constexpr struct __get_early_domain_t {
     template <class _Sender, class _Default = default_domain>
     auto operator()(const _Sender&, _Default __def = {}) const noexcept {
diff --git a/include/stdexec/__detail/__let.hpp b/include/stdexec/__detail/__let.hpp
index c872028b2..18742ebcd 100644
--- a/include/stdexec/__detail/__let.hpp
+++ b/include/stdexec/__detail/__let.hpp
@@ -337,6 +337,8 @@ namespace stdexec {
       };
     }
 
+    //! Metafunction creating the operation state needed to connect the result of calling
+    //! the sender factory function, `_Fun`, and passing its result to a receiver.
     template <class _Receiver, class _Fun, class _Set, class _Sched>
     struct __op_state_for {
       template <class... _Args>
@@ -346,6 +348,8 @@ namespace stdexec {
         _Receiver>;
     };
 
+    //! The core of the operation state for `let_*`.
+    //! This gets bundled up into a larger operation state (`__detail::__op_state<...>`).
     template <class _Receiver, class _Fun, class _Set, class _Sched, class... _Tuples>
     struct __let_state {
       using __fun_t = _Fun;
@@ -385,10 +389,14 @@ namespace stdexec {
       _Fun __fun_;
       STDEXEC_IMMOVABLE_NO_UNIQUE_ADDRESS
       _Sched __sched_;
+      //! Variant to hold the results passed from upstream before passing them to the function:
       __result_variant __args_{};
+      //! Variant type for holding the operation state from connecting 
+      //! the function result to the downstream receiver:
       __op_state_variant __op_state3_{};
     };
 
+    //! Implementation of the `let_*_t` types, where `_Set` is, e.g., `set_value_t` for `let_value`.
     template <class _Set, class _Domain>
     struct __let_t {
       using __domain_t = _Domain;
@@ -471,11 +479,18 @@ namespace stdexec {
             });
         };
 
+      //! Helper function to actually invoke the function to produce `let_*`'s sender,
+      //! connect it to the downstream receiver, and start it.
+      //! This is the heart of `let_*`.
       template <class _State, class _OpState, class... _As>
       static void __bind_(_State& __state, _OpState& __op_state, _As&&... __as) {
+        // Store the passed-in (received) args:
         auto& __args = __state.__args_.emplace_from(__tup::__mktuple, static_cast<_As&&>(__as)...);
+        // Apply the function to the args to get the sender:
         auto __sndr2 = __args.apply(std::move(__state.__fun_), __args);
+        // Create a receiver based on the state, the computed sender, and the operation state:
         auto __rcvr2 = __state.__get_result_receiver(__sndr2, __op_state);
+        // Connect the sender to the receiver and start it:
         auto& __op2 = __state.__op_state3_.emplace_from(
           stdexec::connect, std::move(__sndr2), std::move(__rcvr2));
         stdexec::start(__op2);
@@ -514,8 +529,10 @@ namespace stdexec {
           _Tag,
           _As&&... __as) noexcept -> void {
         if constexpr (__same_as<_Tag, _Set>) {
+          // Intercept the channel of interest to compute the sender and connect it:
           __bind(__op_state, static_cast<_As&&>(__as)...);
         } else {
+          // Forward the other channels downstream:
           using _Receiver = decltype(__op_state.__rcvr_);
           _Tag()(static_cast<_Receiver&&>(__op_state.__rcvr_), static_cast<_As&&>(__as)...);
         }
diff --git a/include/stdexec/__detail/__meta.hpp b/include/stdexec/__detail/__meta.hpp
index 2ab262043..f793ca24b 100644
--- a/include/stdexec/__detail/__meta.hpp
+++ b/include/stdexec/__detail/__meta.hpp
@@ -94,9 +94,11 @@ namespace stdexec {
   using __msize_t = __muchar (*)[_Np + 1]; // +1 to avoid zero-size array
 #endif
 
+  //! Metafunction selects the first of two type arguments.
   template <class _Tp, class _Up>
   using __mfirst = _Tp;
 
+  //! Metafunction selects the second of two type arguments.
   template <class _Tp, class _Up>
   using __msecond = _Up;
 
@@ -327,6 +329,9 @@ namespace stdexec {
   template <class... _Args>
   concept _Ok = (STDEXEC_IS_SAME(__ok_t<_Args>, __msuccess) && ...);
 
+  //! If both are true:
+  //! Then __i<true, true>::__g<F, Args...> is an alias for F<Args...>
+  //! and __i<true, true>::__f<F> is an alias for F. 
   template <bool _ArgsOK, bool _FnOK = true>
   struct __i;
 
@@ -419,6 +424,7 @@ namespace stdexec {
     using __f = _Fn;
   };
 
+  //! Metafunction takes a function and provides a checked version of it?
   template <template <class...> class _Fn>
   struct __q {
     template <class... _Args>
@@ -505,6 +511,9 @@ namespace stdexec {
   using __mmemoize_q = __mmemoize<__q<_Fn>, _Args...>;
 
   struct __if_ {
+    //! Metafunction selects `_True` if the bool template is `true`, otherwise the second.
+    //! That is, `__<true>::__f<A, B>` is `A` and `__false<>::__f<A, B>` is B.
+    //! This is similar to `std::conditional_t<Cond, A, B>`.
     template <bool>
     struct __ {
       template <class _True, class...>
@@ -515,6 +524,7 @@ namespace stdexec {
     using __f = __minvoke<__<static_cast<bool>(__v<_Pred>)>, _True, _False...>;
   };
 
+  // Specialization; see above.
   template <>
   struct __if_::__<false> {
     template <class, class _False>
diff --git a/include/stdexec/__detail/__starts_on.hpp b/include/stdexec/__detail/__starts_on.hpp
index 239bd17e3..34d0f2f4c 100644
--- a/include/stdexec/__detail/__starts_on.hpp
+++ b/include/stdexec/__detail/__starts_on.hpp
@@ -32,6 +32,7 @@
 
 namespace stdexec {
   namespace __detail {
+    //! Constant function object always returning `__val_`.
     template <class _Ty, class = __name_of<__decay_t<_Ty>>>
     struct __always {
       _Ty __val_;
@@ -81,6 +82,7 @@ namespace stdexec {
         return __sexpr_apply(
           static_cast<_Sender&&>(__sndr),
           []<class _Data, class _Child>(__ignore, _Data&& __data, _Child&& __child) {
+            // This is the heart of starts_on: It uses `let_value` to schedule `__child` on the given scheduler:
             return let_value(schedule(__data), __detail::__always{static_cast<_Child&&>(__child)});
           });
       }

From 7e1a3b4520be002b6630a288d75fbcd09932d3d5 Mon Sep 17 00:00:00 2001
From: Ben FrantzDale <benfrantzdale@gmail.com>
Date: Wed, 9 Oct 2024 10:41:39 -0400
Subject: [PATCH 3/8] Document bulk including the static_thread_pool
 customization.

---
 include/exec/static_thread_pool.hpp | 24 ++++++++++++++++++++++--
 include/stdexec/__detail/__bulk.hpp |  6 ++++++
 2 files changed, 28 insertions(+), 2 deletions(-)

diff --git a/include/exec/static_thread_pool.hpp b/include/exec/static_thread_pool.hpp
index e575aee9f..cd79194b7 100644
--- a/include/exec/static_thread_pool.hpp
+++ b/include/exec/static_thread_pool.hpp
@@ -475,6 +475,11 @@ namespace exec {
         const nodemask& contraints = nodemask::any()) noexcept;
       void enqueue(remote_queue& queue, task_base* task, std::size_t threadIndex) noexcept;
 
+      //! Enqueue a contiguous span of tasks across task queues.
+      //! Note: We use the concrete `TaskT` because we enqueue
+      //! tasks `task + 0`, `task + 1`, etc. so std::span<task_base>
+      //! wouldn't be correct.
+      //! This is O(n_threads) on the calling thread.
       template <std::derived_from<task_base> TaskT>
       void bulk_enqueue(TaskT* task, std::uint32_t n_threads) noexcept;
       void bulk_enqueue(
@@ -810,12 +815,15 @@ namespace exec {
 
     template <std::derived_from<task_base> TaskT>
     void static_thread_pool_::bulk_enqueue(TaskT* task, std::uint32_t n_threads) noexcept {
-      auto& queue = *get_remote_queue();
+      auto& queue = *this->get_remote_queue();
       for (std::uint32_t i = 0; i < n_threads; ++i) {
-        std::uint32_t index = i % available_parallelism();
+        std::uint32_t index = i % this->available_parallelism();
         queue.queues_[index].push_front(task + i);
         threadStates_[index]->notify();
       }
+      // At this point the calling thread can exit and the pool will take over.
+      // Ultimately, the last completing thread passes the result forward.
+      // See `if (is_last_thread)` above.
     }
 
     inline void static_thread_pool_::bulk_enqueue(
@@ -1115,8 +1123,11 @@ namespace exec {
       }
     };
 
+    //! The customized operation state for `stdexec::bulk` operations
     template <class CvrefSender, class Receiver, class Shape, class Fun, bool MayThrow>
     struct static_thread_pool_::bulk_shared_state {
+      //! The actual `bulk_task` holds a pointer to the shared state
+      //! and its `__execute` function reads from that shared state.
       struct bulk_task : task_base {
         bulk_shared_state* sh_state_;
 
@@ -1127,6 +1138,9 @@ namespace exec {
             auto total_threads = sh_state.num_agents_required();
 
             auto computation = [&](auto&... args) {
+              // Each computation does one or more call to the the bulk function.
+              // In the case that the shape is much larger than the total number of threads,
+              // then each call to computation will call the function many times.
               auto [begin, end] = even_share(sh_state.shape_, tid, total_threads);
               for (Shape i = begin; i < end; ++i) {
                 sh_state.fun_(i, args...);
@@ -1192,6 +1206,8 @@ namespace exec {
       std::exception_ptr exception_;
       std::vector<bulk_task> tasks_;
 
+      //! The number of agents required is the minimum of `shape_` and the available parallelism.
+      //! That is, we don't need an agent for each of the shape values.
       [[nodiscard]]
       auto num_agents_required() const -> std::uint32_t {
         return static_cast<std::uint32_t>(
@@ -1205,6 +1221,8 @@ namespace exec {
           data_);
       }
 
+      //! Construct from a pool, receiver, shape, and function.
+      //! Allocates O(min(shape, available_parallelism())) memory.
       bulk_shared_state(static_thread_pool_& pool, Receiver rcvr, Shape shape, Fun fun)
         : pool_{pool}
         , rcvr_{static_cast<Receiver&&>(rcvr)}
@@ -1215,6 +1233,8 @@ namespace exec {
       }
     };
 
+
+    //! A customized receiver to allow parallel execution of `stdexec::bulk` operations:
     template <class CvrefSenderId, class ReceiverId, class Shape, class Fun, bool MayThrow>
     struct static_thread_pool_::bulk_receiver<CvrefSenderId, ReceiverId, Shape, Fun, MayThrow>::__t {
       using __id = bulk_receiver;
diff --git a/include/stdexec/__detail/__bulk.hpp b/include/stdexec/__detail/__bulk.hpp
index 012f0b5a6..d832495c2 100644
--- a/include/stdexec/__detail/__bulk.hpp
+++ b/include/stdexec/__detail/__bulk.hpp
@@ -122,6 +122,10 @@ namespace stdexec {
         return {};
       };
 
+      //! This implements the core default behavior for `bulk`:
+      //! When setting value, it loops over the shape and invokes the function.
+      //! Note: This is not done in parallel. That is customized by the scheduler.
+      //! See, e.g., static_thread_pool::bulk_receiver::__t.
       static constexpr auto complete = //
         []<class _Tag, class _State, class _Receiver, class... _Args>(
           __ignore,
@@ -130,8 +134,10 @@ namespace stdexec {
           _Tag,
           _Args&&... __args) noexcept -> void {
         if constexpr (std::same_as<_Tag, set_value_t>) {
+          // Intercept set_value and dispatch to the bulk operation.
           using __shape_t = decltype(__state.__shape_);
           if constexpr (noexcept(__state.__fun_(__shape_t{}, __args...))) {
+            // The noexcept version that doesn't need try/catch:
             for (__shape_t __i{}; __i != __state.__shape_; ++__i) {
               __state.__fun_(__i, __args...);
             }

From 0c713f39a08725571c3c026ab706b16bac6ed005 Mon Sep 17 00:00:00 2001
From: Ben FrantzDale <benfrantzdale@gmail.com>
Date: Wed, 9 Oct 2024 10:53:12 -0400
Subject: [PATCH 4/8] Little comment on `__shared_state`.

---
 include/stdexec/__detail/__shared.hpp | 1 +
 1 file changed, 1 insertion(+)

diff --git a/include/stdexec/__detail/__shared.hpp b/include/stdexec/__detail/__shared.hpp
index 995fb4cc9..ffba26a75 100644
--- a/include/stdexec/__detail/__shared.hpp
+++ b/include/stdexec/__detail/__shared.hpp
@@ -203,6 +203,7 @@ namespace stdexec {
       return &__tombstone_;
     }
 
+    //! Heap-allocatable shared state for things like `stdexec::split`.
     template <class _CvrefSender, class _Env>
     struct __shared_state
       : private __enable_intrusive_from_this<__shared_state<_CvrefSender, _Env>, 2> {

From eb38b43873f4d6aab09cf1e1169af1c78598b277 Mon Sep 17 00:00:00 2001
From: Eric Niebler <eniebler@boost.org>
Date: Mon, 21 Oct 2024 12:11:03 -0700
Subject: [PATCH 5/8] Update include/stdexec/__detail/__meta.hpp

---
 include/stdexec/__detail/__meta.hpp | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/include/stdexec/__detail/__meta.hpp b/include/stdexec/__detail/__meta.hpp
index f793ca24b..7093c7e0a 100644
--- a/include/stdexec/__detail/__meta.hpp
+++ b/include/stdexec/__detail/__meta.hpp
@@ -512,7 +512,7 @@ namespace stdexec {
 
   struct __if_ {
     //! Metafunction selects `_True` if the bool template is `true`, otherwise the second.
-    //! That is, `__<true>::__f<A, B>` is `A` and `__false<>::__f<A, B>` is B.
+    //! That is, `__<true>::__f<A, B>` is `A` and `__<false>::__f<A, B>` is B.
     //! This is similar to `std::conditional_t<Cond, A, B>`.
     template <bool>
     struct __ {

From 337956cecfcadf07c6e9571127c7ee541f5f84f7 Mon Sep 17 00:00:00 2001
From: Ben FrantzDale <benfrantzdale@gmail.com>
Date: Mon, 21 Oct 2024 16:25:31 -0400
Subject: [PATCH 6/8] Clarify __q comments.

---
 include/stdexec/__detail/__meta.hpp | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/include/stdexec/__detail/__meta.hpp b/include/stdexec/__detail/__meta.hpp
index 7093c7e0a..d0479708d 100644
--- a/include/stdexec/__detail/__meta.hpp
+++ b/include/stdexec/__detail/__meta.hpp
@@ -424,7 +424,14 @@ namespace stdexec {
     using __f = _Fn;
   };
 
-  //! Metafunction takes a function and provides a checked version of it?
+  //! This struct template is like [mpl::quote](https://www.boost.org/doc/libs/1_86_0/libs/mpl/doc/refmanual/quote.html).
+  //! It turns an alias/class template into a metafunction that also propagates "meta-exceptions".
+  //! All of the meta utilities recognize specializations of stdexec::_ERROR_ as an error type. 
+  //! Error types short-circuit the evaluation of the metafunction and are automatically propagated like an exception. 
+  //! Note: `__minvoke` and `__meval` also participate in this error propagation.
+  //!
+  //! This design lets us report type errors briefly at the library boundary, even if the 
+  //! actual error happens deep inside a meta-program.
   template <template <class...> class _Fn>
   struct __q {
     template <class... _Args>

From ee22ceac62b7d423a52bd74a63cdca83199d9e49 Mon Sep 17 00:00:00 2001
From: Ben FrantzDale <benfrantzdale@gmail.com>
Date: Mon, 21 Oct 2024 17:33:34 -0400
Subject: [PATCH 7/8] Annotate `__manual_lifetime`.

---
 .../stdexec/__detail/__manual_lifetime.hpp    | 22 ++++++++++++++++---
 1 file changed, 19 insertions(+), 3 deletions(-)

diff --git a/include/stdexec/__detail/__manual_lifetime.hpp b/include/stdexec/__detail/__manual_lifetime.hpp
index d2d44aebe..7650b432f 100644
--- a/include/stdexec/__detail/__manual_lifetime.hpp
+++ b/include/stdexec/__detail/__manual_lifetime.hpp
@@ -25,12 +25,16 @@
 
 namespace stdexec {
 
+  //! Holds storage for a `_Ty`, but allows clients to `__construct(...)`, `__destry()`, 
+  //! and `__get()` the `_Ty` without regard for usual lifetime rules.
   template <class _Ty>
   class __manual_lifetime {
    public:
+    //! Constructor does nothing: It's on you to call `__construct(...)` or `__construct_from(...)`
+    //! if you want the `_Ty`'s lifetime to begin.
     constexpr __manual_lifetime() noexcept {
     }
-
+    //! Destructor does nothing: It's on you to call `__destroy()` if you mean to.
     constexpr ~__manual_lifetime() {
     }
 
@@ -40,6 +44,8 @@ namespace stdexec {
     __manual_lifetime(__manual_lifetime&&) = delete;
     auto operator=(__manual_lifetime&&) -> __manual_lifetime& = delete;
 
+    //! Construct the `_Ty` in place. 
+    //! There are no safeties guarding against the case that there's already one there.
     template <class... _Args>
     auto __construct(_Args&&... __args) noexcept(
       stdexec::__nothrow_constructible_from<_Ty, _Args...>) -> _Ty& {
@@ -49,6 +55,8 @@ namespace stdexec {
                              _Ty{static_cast<_Args&&>(__args)...});
     }
 
+    //! Construct the `_Ty` in place from the result of calling `func`.
+    //! There are no safeties guarding against the case that there's already one there.
     template <class _Func, class... _Args>
     auto __construct_from(_Func&& func, _Args&&... __args) -> _Ty& {
       // Use placement new instead of std::construct_at in case the function returns an immovable
@@ -56,23 +64,31 @@ namespace stdexec {
       return *std::launder(::new (static_cast<void*>(__buffer_))
                              _Ty{(static_cast<_Func&&>(func))(static_cast<_Args&&>(__args)...)});
     }
-
+    //! End the lifetime of the contained `_Ty`.
+    //! Precondition: The lifetime has started.
     void __destroy() noexcept {
       std::destroy_at(&__get());
     }
-
+    //! Get access to the `_Ty`.
+    //! Precondition: The lifetime has started.
     auto __get() & noexcept -> _Ty& {
       return *reinterpret_cast<_Ty*>(__buffer_);
     }
 
+    //! Get access to the `_Ty`.
+    //! Precondition: The lifetime has started.
     auto __get() && noexcept -> _Ty&& {
       return static_cast<_Ty&&>(*reinterpret_cast<_Ty*>(__buffer_));
     }
 
+    //! Get access to the `_Ty`.
+    //! Precondition: The lifetime has started.
     auto __get() const & noexcept -> const _Ty& {
       return *reinterpret_cast<const _Ty*>(__buffer_);
     }
 
+    //! Move semantics aren't supported.
+    //! If you want to move the `_Ty`, use `std::move(ml.__get())`.
     auto __get() const && noexcept -> const _Ty&& = delete;
 
    private:

From 05224d55b4ddb51aa49870d17981da6c35fbd44a Mon Sep 17 00:00:00 2001
From: Ben FrantzDale <benfrantzdale@gmail.com>
Date: Thu, 24 Oct 2024 13:30:48 -0400
Subject: [PATCH 8/8] Add Eric's comments from the PR about `__i` and
 `__basic_sender` and `__sexpr`.

---
 include/stdexec/__detail/__basic_sender.hpp |  8 +++++---
 include/stdexec/__detail/__meta.hpp         | 12 +++++++++---
 2 files changed, 14 insertions(+), 6 deletions(-)

diff --git a/include/stdexec/__detail/__basic_sender.hpp b/include/stdexec/__detail/__basic_sender.hpp
index 965264534..475ea7158 100644
--- a/include/stdexec/__detail/__basic_sender.hpp
+++ b/include/stdexec/__detail/__basic_sender.hpp
@@ -500,8 +500,8 @@ namespace stdexec {
   using __get_attrs_fn =
     __result_of<__detail::__drop_front, __mtypeof<__sexpr_impl<_Tag>::get_attrs>>;
 
-  //////////////////////////////////////////////////////////////////////////////////////////////////
-  // __basic_sender
+  //! A dummy type used only for diagnostic purposes. 
+  //! See `__sexpr` for the implementation of P2300's _`basic-sender`_.
   template <class...>
   struct __basic_sender {
     // See MAINTAINERS.md#class-template-parameters for `__id` and `__t`.
@@ -510,7 +510,9 @@ namespace stdexec {
   };
 
   //! A struct template to aid in creating senders.
-  //! A `__sexpr<Desc>` 
+  //! This struct closely resembles P2300's [_`basic-sender`_](https://eel.is/c++draft/exec#snd.expos-24),
+  //! but is not an exact implementation.
+  //! Note: The struct named `__basic_sender` is just a dummy type and is also not _`basic-sender`_.
   template <auto _DescriptorFn, class = __anon>
   struct __sexpr {
     using sender_concept = sender_t;
diff --git a/include/stdexec/__detail/__meta.hpp b/include/stdexec/__detail/__meta.hpp
index d0479708d..42137ce17 100644
--- a/include/stdexec/__detail/__meta.hpp
+++ b/include/stdexec/__detail/__meta.hpp
@@ -329,9 +329,15 @@ namespace stdexec {
   template <class... _Args>
   concept _Ok = (STDEXEC_IS_SAME(__ok_t<_Args>, __msuccess) && ...);
 
-  //! If both are true:
-  //! Then __i<true, true>::__g<F, Args...> is an alias for F<Args...>
-  //! and __i<true, true>::__f<F> is an alias for F. 
+  //! The struct `__i` is the implementation of P2300's  
+  //! [_`META-APPLY`_](https://eel.is/c++draft/exec#util.cmplsig-5).
+  //! > [Note [1](https://eel.is/c++draft/exec#util.cmplsig-note-1): 
+  //! > The purpose of META-APPLY is to make it valid to use non-variadic 
+  //! > templates as Variant and Tuple arguments to gather-signatures. — end note]
+  //! In addition to avoiding the dreaded "pack expanded into non-pack argument" error,
+  //! it is part of the meta-error propagation mechanism. if any of the argument types 
+  //! are a specialization of `_ERROR_`, `__i` will short-circuit and return the error.
+  //! `__minvoke` and `__meval` are implemented in terms of `__i`.
   template <bool _ArgsOK, bool _FnOK = true>
   struct __i;