fix(sidekick/swift): note Discovery LRO return type

internal/sidekick/swift/generate_service_comments_test.go

@@ -79,3 +79,78 @@ func TestGenerateService_DocComments(t *testing.T) {
 		t.Errorf("mismatch (-want +got):\n%s", diff)
 	}
 }
+
+func TestGenerateService_DiscoveryLRODocComments(t *testing.T) {
+	outDir := t.TempDir()
+
+	req := api.NewTestMessage("InsertInstanceRequest").
+		WithPackage("google.cloud.compute.v1").
+		WithFields(
+			api.NewTestField("project").WithType(api.TypezString),
+			api.NewTestField("zone").WithType(api.TypezString),
+		)
+	op := api.NewTestMessage("Operation").
+		WithPackage("google.cloud.compute.v1")
+
+	method := api.NewTestMethod("Insert").
+		WithDocumentation("Creates an instance resource.").
+		WithInput(req).
+		WithOutput(op).
+		WithVerb("POST").
+		WithPathTemplate((&api.PathTemplate{}).WithLiteral("compute").WithLiteral("v1").WithLiteral("projects").WithVariableNamed("project").WithLiteral("zones").WithVariableNamed("zone").WithLiteral("instances")).
+		WithDiscoveryLro(&api.DiscoveryLro{
+			PollingPathParameters: []string{"project", "zone"},
+		})
+
+	service := api.NewTestService("Instances").
+		WithDocumentation("The Instances API.").
+		WithPackage("google.cloud.compute.v1").
+		WithMethods(method)
+
+	model := api.NewTestAPI([]*api.Message{req, op}, nil, []*api.Service{service})
+
+	library := &config.Library{
+		Swift: swiftConfig(t, []config.SwiftDependency{
+			{Name: "GoogleGax", RequiredByServices: true},
+			{ApiPackage: "google.cloud.compute.v1", Name: "GoogleCloudComputeV1"},
+		}),
+	}
+	if err := Generate(t.Context(), model, outDir, library, nil); err != nil {
+		t.Fatal(err)
+	}
+
+	filename := filepath.Join(outDir, "Sources", "GoogleCloudComputeV1", "Instances.swift")
+	content, err := os.ReadFile(filename)
+	if err != nil {
+		t.Fatal(err)
+	}
+	contentStr := string(content)
+
+	// Verify Discovery LRO method documentation includes the - Note: callout
+	wantMethod := `  /// Creates an instance resource.
+  ///
+  /// - Note: Unlike standard gRPC long-running operations where polling returns the resulting
+  ///   resource, Discovery-based operations return the terminal ` + "`GoogleCloudComputeV1.Operation`" + `
+  ///   status object. To obtain the created or modified resource, invoke the corresponding ` + "`get`" + `
+  ///   method once the operation completes.
+  ///
+  /// @Snippet(path: "Instances_Insert")
+  public func insertPollingUntilDone`
+	gotMethod := extractBlock(t, contentStr, "  /// Creates an instance resource.\n  ///\n  /// - Note: Unlike standard gRPC long-running operations where polling returns the resulting", "public func insertPollingUntilDone")
+	if diff := cmp.Diff(wantMethod, gotMethod); diff != "" {
+		t.Errorf("mismatch (-want +got):\n%s", diff)
+	}
+
+	// Verify protocol documentation includes the - Note: callout
+	wantProtocol := `    /// See ` + "`InstancesClient.insert`" + `.
+    ///
+    /// - Note: Unlike standard gRPC long-running operations where polling returns the resulting
+    ///   resource, Discovery-based operations return the terminal ` + "`GoogleCloudComputeV1.Operation`" + `
+    ///   status object. To obtain the created or modified resource, invoke the corresponding ` + "`get`" + `
+    ///   method once the operation completes.
+    func insertPollingUntilDone`
+	gotProtocol := extractBlock(t, contentStr, "    /// See `InstancesClient.insert`.\n    ///\n    /// - Note: Unlike standard gRPC long-running operations where polling returns the resulting", "func insertPollingUntilDone")
+	if diff := cmp.Diff(wantProtocol, gotProtocol); diff != "" {
+		t.Errorf("mismatch (-want +got):\n%s", diff)
+	}
+}

internal/sidekick/swift/templates/common/client_protocol.gotmpl

@@ -46,6 +46,11 @@ extension Clients {
     {{- end }}
     {{- if .Codec.DiscoveryLRO }}
     /// See `{{ .Service.Codec.ClientName }}.{{ .Codec.Name }}`.
+    ///
+    /// - Note: Unlike standard gRPC long-running operations where polling returns the resulting
+    ///   resource, Discovery-based operations return the terminal `{{ .Codec.DiscoveryLRO.ReturnType }}`
+    ///   status object. To obtain the created or modified resource, invoke the corresponding `get`
+    ///   method once the operation completes.
     {{- if .Deprecated }}
     @available(*, deprecated)
     {{- end }}

internal/sidekick/swift/templates/common/service.swift.gotmpl

@@ -143,6 +143,13 @@ public final class {{ .Codec.ClientName }}: Clients.{{ .Codec.StubPrefix }}Proto
   {{- range .Codec.DocLines }}
   /// {{ . }}
   {{- end }}
+  {{- if .Codec.DocLines }}
+  ///
+  {{- end }}
+  /// - Note: Unlike standard gRPC long-running operations where polling returns the resulting
+  ///   resource, Discovery-based operations return the terminal `{{ .Codec.DiscoveryLRO.ReturnType }}`
+  ///   status object. To obtain the created or modified resource, invoke the corresponding `get`
+  ///   method once the operation completes.
   ///
   /// @Snippet(path: "{{ .Service.Name }}_{{ .Name }}")
   {{- if .Deprecated }}