Merge branch 'cg-cancel-nicely' into cg-initiator

src/core/lib/channel/promise_based_filter.h

@@ -572,6 +572,7 @@ MakeFilterCall(Derived* derived) {
 template <typename Derived>
 class ImplementChannelFilter : public ChannelFilter {
  public:
+  // Natively construct a v3 call.
   void InitCall(CallSpineInterface* call_spine) {
     auto* call = GetContext<Arena>()->ManagedNew<typename Derived::Call>();
     promise_filter_detail::InterceptClientInitialMetadata(
@@ -591,6 +592,9 @@ class ImplementChannelFilter : public ChannelFilter {
         static_cast<Derived*>(this), call_spine);
   }
 
+  // Polyfill for the original promise scheme.
+  // Allows writing v3 filters that work with v2 stacks.
+  // (and consequently also v1 stacks since we can polyfill back to that too).
   ArenaPromise<ServerMetadataHandle> MakeCallPromise(
       CallArgs call_args, NextPromiseFactory next_promise_factory) final {
     auto* call = promise_filter_detail::MakeFilterCall<Derived>(

src/core/lib/transport/transport.h

@@ -228,6 +228,14 @@ struct CallArgs {
   PipeSender<MessageHandle>* server_to_client_messages;
 };
 
+using NextPromiseFactory =
+    std::function<ArenaPromise<ServerMetadataHandle>(CallArgs)>;
+
+// The common middle part of a call - a reference is held by each of
+// CallInitiator and CallHandler - which provide interfaces that are appropriate
+// for each side of a call.
+// The spine will ultimately host the pipes, filters, and context for one part
+// of a call: ie top-half client channel, sub channel call, server call.
 // TODO(ctiller): eventually drop this when we don't need to reference into
 // legacy promise calls anymore
 class CallSpineInterface {
@@ -462,9 +470,6 @@ auto OutgoingMessages(CallHalf& h) {
   return Wrapper{h};
 }
 
-using NextPromiseFactory =
-    std::function<ArenaPromise<ServerMetadataHandle>(CallArgs)>;
-
 }  // namespace grpc_core
 
 // forward declarations