Go SDK: trim the comments of the Dag parse path

The comments now state the behavior in one or two lines.

Co-Authored-By: Claude <noreply@anthropic.com>

Author: jason810496

go-sdk/airflow/bundle.go

@@ -195,7 +195,7 @@ func (m *taskHandlerMap) ListTaskHandlers() []bundle.TaskHandlerInfo {
 	return slices.Clone(m.order)
 }
 
-// dagMap holds the registered Dags by dag_id and keeps the order in which they were registered.
+// dagMap holds the registered Dags by dag_id, in registration order.
 type dagMap struct {
 	mu    sync.Mutex
 	dags  map[string]*DagRef
@@ -225,9 +225,8 @@ func (m *dagMap) has(dagID string) bool {
 	return exists
 }
 
-// serialize serializes the registered Dags in the order they were registered. If serializing a Dag
-// panics, the panic becomes the error of that Dag instead of ending the parse. The import error of
-// the parse then names the Dag.
+// serialize serializes the Dags in registration order. If a Dag panics, the panic becomes that
+// Dag's Err.
 func (m *dagMap) serialize(fileloc, relativeFileloc string) []bundle.SerializedDag {
 	m.mu.Lock()
 	dags := slices.Clone(m.order)

go-sdk/airflow/bundle_test.go

@@ -418,8 +418,7 @@ func TestSerializeDagsKeepsTheOtherDagsWhenADagCannotBeSerialized(t *testing.T)
 	etl := Dag("etl")
 	etl.Task(noop)
 	b.Register(etl)
-	// Register checks and expands every Dag it takes. A Dag that skipped Register therefore stands
-	// in for a Dag that the serializer fails on.
+	// A Dag that skipped Register stands in for one the serializer fails on.
 	broken := Dag("broken")
 	b.dags.dags["broken"] = broken
 	b.dags.order = append(b.dags.order, broken)

go-sdk/airflow/dag.go

@@ -71,9 +71,8 @@ type DagRef struct {
 // [IfRef.Then], [IfRef.Else], [SwitchRef.Case] and the methods of [TaskGroupRef] panic once the Dag
 // is registered.
 //
-// When the Dag processor asks to parse the bundle, [BundleRef.Serve] answers with the registered
-// Dags in serialized form. Serve does not yet list these Dags in the --airflow-metadata manifest or
-// run their tasks.
+// [BundleRef.Serve] sends the registered Dags to the Dag processor, but does not yet list them in
+// the --airflow-metadata manifest or run their tasks.
 //
 // Dag panics if it gets more than one DagSpec, or if the DagSpec has a value that Python rejects
 // when it builds or validates a Dag:

go-sdk/airflow/serve.go

@@ -57,10 +57,9 @@ const (
 // The command-line flags of the executable decide what Serve does.
 // With --airflow-metadata it prints the bundle's manifest and returns, which is how
 // airflow-go-pack reads the Dag and task ids of the registered task handlers.
-// Airflow starts the executable with --comm and --logs. With these flags, Serve speaks the
-// coordinator protocol. It either runs one task or answers the Dag processor's request to parse
-// the bundle. To answer a parse request, Serve sends the Dags from [Dag] that the bundle registered
-// and runs no task.
+// Airflow starts the executable with --comm and --logs. Serve then speaks the coordinator
+// protocol and either runs one task or answers the Dag processor's parse request with the Dags
+// from [Dag].
 //
 // main must exit with a non-zero status when Serve returns an error, because the exit status
 // is how the supervisor learns that the task failed:

go-sdk/airflow/serve_test.go

@@ -220,9 +220,8 @@ func TestServeHelpIsNotAnError(t *testing.T) {
 	assert.Contains(t, stdout.String(), "--airflow-metadata")
 }
 
-// serveForSupervisor runs b.serve with --comm and --logs, the same flags that Airflow starts the
-// bundle with. It returns the supervisor's end of the comm socket and the channel that gets what
-// serve returns.
+// serveForSupervisor runs b.serve with --comm and --logs and returns the supervisor's end of the
+// comm socket and the channel that gets what serve returns.
 func serveForSupervisor(t *testing.T, b *BundleRef) (*execution.CoordinatorComm, <-chan error) {
 	t.Helper()
 	commLn, err := net.Listen("tcp", "127.0.0.1:0")
@@ -294,8 +293,7 @@ func TestServeRunsTaskForSupervisor(t *testing.T) {
 	assert.True(t, ran)
 }
 
-// To parse the bundle, the Dag processor starts it with --comm and --logs and then sends a
-// DagFileParseRequest over the comm socket.
+// The Dag processor sends a DagFileParseRequest instead of StartupDetails.
 func TestServeAnswersTheDagParseRequestWithoutRunningATask(t *testing.T) {
 	var ran []string
 	record := func(name string) func(Context) error {

go-sdk/internal/bundle/doc.go

@@ -15,11 +15,10 @@
 // specific language governing permissions and limitations
 // under the License.
 
-// Package bundle defines what the coordinator runtime needs from a bundle. The
-// runtime needs the tasks to look up and run, and the Dag and task ids to list
-// in the manifest. It also needs the serialized Dags to send in answer to a Dag
-// parse request.
+// Package bundle defines what the coordinator runtime needs from a bundle: the
+// tasks it looks up and runs, the Dag and task ids it lists in the manifest, and
+// the serialized Dags it sends to the Dag processor.
 //
-// Package airflow builds the tasks, the ids, and the serialized Dags from the
-// task handlers and the Dags that a bundle registers.
+// Package airflow builds the tasks and ids from the task handlers a bundle
+// registers, and the serialized Dags from its Dags.
 package bundle

go-sdk/pkg/execution/dag_parse_test.go

@@ -33,8 +33,7 @@ import (
 	"github.com/apache/airflow/go-sdk/pkg/execution/genmodels"
 )
 
-// serializedDags serializes the Dags it holds. It also records the fileloc and relativeFileloc
-// that SerializeDags was called with.
+// serializedDags is a DagSerializer that records the paths it was called with.
 type serializedDags struct {
 	dags              []bundle.SerializedDag
 	fileloc, relative string
@@ -60,8 +59,7 @@ var etlParseRequest = &genmodels.DagFileParseRequest{
 
 func discardLogger() *slog.Logger { return slog.New(slog.NewTextHandler(io.Discard, nil)) }
 
-// wireJSON passes body through the frame encoding that SendRequest uses and returns the result as
-// JSON. A test then sees the keys, nulls and empty lists that the Dag processor receives.
+// wireJSON returns body as the Dag processor receives it, after the frame encoding of SendRequest.
 func wireJSON(t *testing.T, body any) string {
 	t.Helper()
 	payload, err := encodeRequest(0, body)

go-sdk/pkg/execution/integration_test.go

@@ -1361,8 +1361,8 @@ func TestServeFailureAfterConnectClosesComm(t *testing.T) {
 	logsConn := <-logsCh
 	defer logsConn.Close()
 
-	// Serve expects StartupDetails or DagFileParseRequest as the first frame, so it fails to
-	// decode a VariableResult.
+	// Serve expects StartupDetails or DagFileParseRequest first, so it fails to decode a
+	// VariableResult.
 	payload, err := encodeRequest(
 		0,
 		map[string]any{"type": "VariableResult", "key": "k", "value": "v"},

go-sdk/pkg/execution/server.go

@@ -20,11 +20,8 @@
 // the Airflow supervisor (Python ExecutableCoordinator), the Serve method of
 // airflow.BundleRef dispatches here.
 //
-// The first frame that the runtime reads on the comm socket decides what the
-// runtime does. After a StartupDetails message, the runtime runs a task over
-// several rounds of messages. After a DagFileParseRequest from the Dag
-// processor, the runtime runs no task. It answers with one DagFileParsingResult
-// that holds the Dags from airflow.Dag that the bundle registered.
+// The first frame on the comm socket picks the mode: StartupDetails runs one
+// task, and DagFileParseRequest is answered with the bundle's serialized Dags.
 //
 // See go-sdk/adr/0003-coordinator-protocol-msgpack-ipc.md.
 package execution