[Concurrency] Add a couple of comments.

Add some documentation comments to the Dispatch and CF executors,
and update the comments for the allocation and private data APIs.

Author: al45tair

stdlib/public/Concurrency/CFExecutor.swift

@@ -43,6 +43,7 @@ enum CoreFoundation {
 
 // .. Main Executor ............................................................
 
+/// A CFRunLoop-based main executor (Apple platforms only)
 @available(StdlibDeploymentTarget 6.2, *)
 public final class CFMainExecutor: DispatchMainExecutor, @unchecked Sendable {
 
@@ -58,6 +59,7 @@ public final class CFMainExecutor: DispatchMainExecutor, @unchecked Sendable {
 
 // .. Task Executor ............................................................
 
+/// A `TaskExecutor` to match `CFMainExecutor` (Apple platforms only)
 @available(StdlibDeploymentTarget 6.2, *)
 public final class CFTaskExecutor: DispatchGlobalTaskExecutor,
                                    @unchecked Sendable {

stdlib/public/Concurrency/DispatchExecutor.swift

@@ -23,6 +23,7 @@ import Swift
 
 // .. Main Executor ............................................................
 
+/// A Dispatch-based main executor.
 @available(StdlibDeploymentTarget 6.2, *)
 public class DispatchMainExecutor: RunLoopExecutor, SchedulingExecutor,
                                    @unchecked Sendable {
@@ -75,6 +76,7 @@ extension DispatchMainExecutor: MainExecutor {}
 
 // .. Task Executor ............................................................
 
+/// A Dispatch-based `TaskExecutor`
 @available(StdlibDeploymentTarget 6.2, *)
 public class DispatchGlobalTaskExecutor: TaskExecutor, SchedulingExecutor,
                                          @unchecked Sendable {

stdlib/public/Concurrency/PartialAsyncTask.swift

@@ -309,7 +309,9 @@ public struct ExecutorJob: Sendable, ~Copyable {
   }
 
   /// Execute a closure, passing it the bounds of the executor private data
-  /// for the job.
+  /// for the job.  The executor is responsible for ensuring that any resources
+  /// referenced from the private data area are cleared up prior to running the
+  /// job.
   ///
   /// Parameters:
   ///
@@ -501,9 +503,8 @@ extension ExecutorJob {
   /// A job-local stack-disciplined allocator.
   ///
   /// This can be used to allocate additional data required by an
-  /// executor implementation; memory allocated in this manner will
-  /// be released automatically when the job is disposed of by the
-  /// runtime.
+  /// executor implementation; memory allocated in this manner must
+  /// be released by the executor before the job is executed.
   ///
   /// N.B. Because this allocator is stack disciplined, explicitly
   /// deallocating memory out-of-order will cause your program to abort.
@@ -531,23 +532,20 @@ extension ExecutorJob {
       return unsafe UnsafeMutableBufferPointer<T>(start: typedBase, count: capacity)
     }
 
-    /// Deallocate previously allocated memory.  Note that the task
-    /// allocator is stack disciplined, so if you deallocate a block of
-    /// memory, all memory allocated after that block is also deallocated.
+    /// Deallocate previously allocated memory.  You must do this in
+    /// reverse order of allocations, prior to running the job.
     public func deallocate(_ buffer: UnsafeMutableRawBufferPointer) {
       unsafe _jobDeallocate(context, buffer.baseAddress!)
     }
 
-    /// Deallocate previously allocated memory.  Note that the task
-    /// allocator is stack disciplined, so if you deallocate a block of
-    /// memory, all memory allocated after that block is also deallocated.
+    /// Deallocate previously allocated memory.  You must do this in
+    /// reverse order of allocations, prior to running the job.
     public func deallocate<T>(_ pointer: UnsafeMutablePointer<T>) {
       unsafe _jobDeallocate(context, UnsafeMutableRawPointer(pointer))
     }
 
-    /// Deallocate previously allocated memory.  Note that the task
-    /// allocator is stack disciplined, so if you deallocate a block of
-    /// memory, all memory allocated after that block is also deallocated.
+    /// Deallocate previously allocated memory.    You must do this in
+    /// reverse order of allocations, prior to running the job.
     public func deallocate<T>(_ buffer: UnsafeMutableBufferPointer<T>) {
       unsafe _jobDeallocate(context, UnsafeMutableRawPointer(buffer.baseAddress!))
     }