refactor(http-client-csharp): dump deprecated description properties

packages/http-client-csharp/emitter/src/lib/client-model-builder.ts

@@ -85,7 +85,8 @@ export function createModel(sdkContext: SdkContext<NetEmitterOptions>): CodeMode
     const clientParameters = fromSdkEndpointParameter(endpointParameter);
     return {
       Name: getClientName(client, parentNames),
-      Description: client.summary ?? client.doc,
+      Summary: client.summary,
+      Doc: client.doc,
       Operations: client.methods
         .filter((m) => m.kind !== "clientaccessor")
         .map((m) =>
@@ -156,7 +157,8 @@ export function createModel(sdkContext: SdkContext<NetEmitterOptions>): CodeMode
       parameters.push({
         Name: parameter.name,
         NameInRequest: parameter.serializedName,
-        Description: parameter.doc,
+        Summary: parameter.summary,
+        Doc: parameter.doc,
         // TODO: we should do the magic in generator
         Type: parameterType,
         Location: RequestLocation.Uri,

packages/http-client-csharp/emitter/src/lib/converter.ts

@@ -122,7 +122,8 @@ export function fromSdkModelType(
       ) /* when tcgc provide a way to identify if the access is override or not, we can get the accessibility from the modelType.access */,
       usage: modelType.usage,
       deprecation: modelType.deprecation,
-      description: modelType.summary ?? modelType.doc,
+      doc: modelType.doc,
+      summary: modelType.summary,
       discriminatorValue: modelType.discriminatorValue,
       decorators: modelType.decorators,
     } as InputModelType;
@@ -185,7 +186,8 @@ export function fromSdkModelType(
       kind: property.kind,
       name: property.name,
       serializedName: serializedName,
-      description: property.summary ?? property.doc,
+      summary: property.summary,
+      doc: property.doc,
       type: fromSdkType(
         targetType,
         context,
@@ -225,7 +227,8 @@ export function fromSdkEnumType(
         enumType.__raw as any,
       ) /* when tcgc provide a way to identify if the access is override or not, we can get the accessibility from the enumType.access,*/,
       deprecation: enumType.deprecation,
-      description: enumType.summary ?? enumType.doc,
+      summary: enumType.summary,
+      doc: enumType.doc,
       isFixed: enumType.isFixed,
       isFlags: enumType.isFlags,
       usage: enumType.usage,
@@ -337,7 +340,7 @@ function fromSdkConstantType(
       values: values,
       crossLanguageDefinitionId: "",
       access: undefined,
-      description: `The ${enumName}`, // TODO -- what should we put here?
+      doc: `The ${enumName}`, // TODO -- what should we put here?
       isFixed: false,
       isFlags: false,
       usage: literalTypeContext.Usage,
@@ -350,7 +353,7 @@ function fromSdkConstantType(
       kind: "enumvalue",
       name: enumValueName,
       value: constantType.value as string | number,
-      description: enumValueName,
+      doc: enumValueName,
       valueType: enumType.valueType,
       enumType: enumType,
     });
@@ -386,7 +389,8 @@ function fromSdkEnumValueType(
     value: enumValueType.value,
     valueType: fromSdkBuiltInType(enumValueType.valueType),
     enumType: fromSdkEnumType(enumValueType.enumType, context, typeMap),
-    description: enumValueType.summary ?? enumValueType.doc,
+    summary: enumValueType.summary,
+    doc: enumValueType.doc,
     decorators: enumValueType.decorators,
   };
 }

packages/http-client-csharp/emitter/src/lib/operation-converter.ts

@@ -30,6 +30,7 @@ import { InputOperation } from "../type/input-operation.js";
 import { InputParameter } from "../type/input-parameter.js";
 import { InputType } from "../type/input-type.js";
 import { convertLroFinalStateVia } from "../type/operation-final-state-via.js";
+import { OperationLongRunning } from "../type/operation-long-running.js";
 import { OperationPaging } from "../type/operation-paging.js";
 import { OperationResponse } from "../type/operation-response.js";
 import { RequestLocation } from "../type/request-location.js";
@@ -75,7 +76,7 @@ export function fromSdkServiceMethod(
       getOperationGroupName(sdkContext, method.operation, sdkContext.sdkPackage.rootNamespace),
     Deprecated: getDeprecated(sdkContext.program, method.__raw!),
     Summary: method.summary,
-    Description: method.doc,
+    Doc: method.doc,
     Accessibility: method.access,
     Parameters: [...parameterMap.values()],
     Responses: [...responseMap.values()],
@@ -181,7 +182,8 @@ function fromSdkHttpOperationParameter(
   return {
     Name: p.name,
     NameInRequest: p.kind === "header" ? normalizeHeaderName(serializedName) : serializedName,
-    Description: p.summary ?? p.doc,
+    Summary: p.summary,
+    Doc: p.doc,
     Type: parameterType,
     Location: getParameterLocation(p),
     IsApiVersion:
@@ -202,7 +204,7 @@ function loadLongRunningOperation(
   method: SdkServiceMethod<SdkHttpOperation>,
   sdkContext: SdkContext<NetEmitterOptions>,
   typeMap: SdkTypeMap,
-): import("../type/operation-long-running.js").OperationLongRunning | undefined {
+): OperationLongRunning | undefined {
   if (method.kind !== "lro") {
     return undefined;
   }
@@ -252,7 +254,8 @@ function fromSdkServiceResponseHeaders(
       ({
         Name: h.__raw!.name,
         NameInResponse: h.serializedName,
-        Description: h.summary ?? h.doc,
+        Summary: h.summary,
+        Doc: h.doc,
         Type: fromSdkType(h.type, sdkContext, typeMap),
       }) as HttpResponseHeader,
   );

packages/http-client-csharp/emitter/src/lib/typespec-server.ts

@@ -2,7 +2,7 @@
 // Licensed under the MIT License. See License.txt in the project root for license information.
 
 import { SdkContext } from "@azure-tools/typespec-client-generator-core";
-import { getDoc } from "@typespec/compiler";
+import { getDoc, getSummary } from "@typespec/compiler";
 import { HttpServer } from "@typespec/http";
 import { getExtensions } from "@typespec/openapi";
 import { NetEmitterOptions } from "../options.js";
@@ -50,7 +50,8 @@ export function resolveServers(
       const variable: InputParameter = {
         Name: name,
         NameInRequest: name,
-        Description: getDoc(context.program, prop),
+        Summary: getSummary(context.program, prop),
+        Doc: getDoc(context.program, prop),
         Type: inputType,
         Location: RequestLocation.Uri,
         IsApiVersion: name.toLowerCase() === "apiversion" || name.toLowerCase() === "api-version",
@@ -73,7 +74,7 @@ export function resolveServers(
       const variable: InputParameter = {
         Name: "host",
         NameInRequest: "host",
-        Description: server.description,
+        Doc: server.description,
         Type: {
           kind: "string",
           name: "string",

packages/http-client-csharp/emitter/src/type/http-response-header.ts

@@ -6,6 +6,7 @@ import { InputType } from "./input-type.js";
 export interface HttpResponseHeader {
   Name: string;
   NameInResponse: string;
-  Description: string;
+  Summary: string;
+  Doc: string;
   Type: InputType;
 }

packages/http-client-csharp/emitter/src/type/input-client.ts

@@ -8,7 +8,8 @@ import { Protocols } from "./protocols.js";
 
 export interface InputClient {
   Name: string;
-  Description?: string;
+  Summary?: string;
+  Doc?: string;
   Operations: InputOperation[];
   Protocol?: Protocols;
   Parent?: string;

packages/http-client-csharp/emitter/src/type/input-operation.ts

@@ -21,7 +21,7 @@ export interface InputOperation {
   ResourceName?: string;
   Summary?: string;
   Deprecated?: string;
-  Description?: string;
+  Doc?: string;
   Accessibility?: string;
   Parameters: InputParameter[];
   Responses: OperationResponse[];

packages/http-client-csharp/emitter/src/type/input-parameter.ts

@@ -12,7 +12,8 @@ export interface VirtualParameter {}
 export interface InputParameter {
   Name: string;
   NameInRequest: string;
-  Description?: string;
+  Summary?: string;
+  Doc?: string;
   Type: InputType;
   Location: RequestLocation;
   DefaultValue?: InputConstant;

packages/http-client-csharp/emitter/src/type/input-type.ts

@@ -11,7 +11,8 @@ import { DateTimeKnownEncoding, DurationKnownEncoding } from "@typespec/compiler
 
 interface InputTypeBase {
   kind: string;
-  description?: string;
+  summary?: string;
+  doc?: string;
   deprecation?: string;
   decorators?: DecoratorInfo[];
 }

packages/http-client-csharp/emitter/test/Unit/model-type.test.ts

@@ -141,7 +141,7 @@ op test(@body input: Pet): Pet;
     const discriminatorProperty = pet?.properties.find((p) => p === pet?.discriminatorProperty);
     strictEqual(discriminatorProperty?.name, "kind");
     strictEqual(discriminatorProperty.serializedName, "kind");
-    strictEqual(discriminatorProperty.description, "The kind of the pet");
+    strictEqual(discriminatorProperty.doc, "The kind of the pet");
     strictEqual(discriminatorProperty.type.kind, "enum");
     strictEqual(discriminatorProperty.type.name, "PetKind");
     strictEqual(discriminatorProperty.type.valueType.kind, "string");
@@ -234,7 +234,7 @@ op test(@body input: Pet): Pet;
     const discriminatorProperty = pet?.properties.find((p) => p === pet?.discriminatorProperty);
     strictEqual(discriminatorProperty?.name, "kind");
     strictEqual(discriminatorProperty.serializedName, "kind");
-    strictEqual(discriminatorProperty.description, "The kind of the pet");
+    strictEqual(discriminatorProperty.doc, "The kind of the pet");
     strictEqual(discriminatorProperty.type.kind, "enum");
     strictEqual(discriminatorProperty.type.name, "PetKind");
     strictEqual(discriminatorProperty.type.valueType.kind, "string");

packages/http-client-csharp/emitter/test/Unit/property-type.test.ts

@@ -95,7 +95,7 @@ describe("Test GetInputType for enum", () => {
     strictEqual(type.kind, "enum");
     strictEqual(type.name, "SimpleEnum");
     strictEqual(type.isFixed, true);
-    strictEqual(type.description, "fixed string enum");
+    strictEqual(type.doc, "fixed string enum");
     strictEqual(type.crossLanguageDefinitionId, "Azure.Csharp.Testing.SimpleEnum");
     strictEqual(type.access, undefined);
     strictEqual(type.valueType.kind, "string");
@@ -142,7 +142,7 @@ describe("Test GetInputType for enum", () => {
     strictEqual(type.name, "FixedIntEnum");
     strictEqual(type.crossLanguageDefinitionId, "Azure.Csharp.Testing.FixedIntEnum");
     strictEqual(type.access, undefined);
-    strictEqual(type.description, "Fixed int enum");
+    strictEqual(type.doc, "Fixed int enum");
     strictEqual(type.valueType.crossLanguageDefinitionId, "TypeSpec.int32");
     strictEqual(type.valueType.kind, "int32");
     strictEqual(type.values.length, 3);
@@ -181,7 +181,7 @@ describe("Test GetInputType for enum", () => {
     strictEqual(type.name, "FixedEnum");
     strictEqual(type.crossLanguageDefinitionId, "Azure.Csharp.Testing.FixedEnum");
     strictEqual(type.access, undefined);
-    strictEqual(type.description, "Fixed enum");
+    strictEqual(type.doc, "Fixed enum");
     strictEqual(type.valueType.kind, "string");
     strictEqual(type.valueType.crossLanguageDefinitionId, "TypeSpec.string");
     strictEqual(type.values.length, 3);

packages/http-client-csharp/generator/Microsoft.Generator.CSharp.ClientModel/src/Providers/ClientOptionsProvider.cs

@@ -9,8 +9,8 @@
 using Microsoft.Generator.CSharp.Input;
 using Microsoft.Generator.CSharp.Primitives;
 using Microsoft.Generator.CSharp.Providers;
+using Microsoft.Generator.CSharp.Utilities;
 using static Microsoft.Generator.CSharp.Snippets.Snippet;
-using System.ClientModel.Primitives;
 
 namespace Microsoft.Generator.CSharp.ClientModel.Providers
 {
@@ -125,9 +125,10 @@ protected override PropertyProvider[] BuildProperties()
                 if (!p.IsEndpoint && !p.IsApiVersion && p.DefaultValue != null)
                 {
                     FormattableString? description = null;
-                    if (p.Description != null)
+                    var parameterDescription = DocHelpers.GetDescription(p.Summary, p.Doc);
+                    if (parameterDescription is not null)
                     {
-                        description = $"{p.Description}";
+                        description = $"{parameterDescription}";
                     }
 
                     var type = ClientModelPlugin.Instance.TypeFactory.CreateCSharpType(p.Type)?.PropertyInitializationType;

packages/http-client-csharp/generator/Microsoft.Generator.CSharp.ClientModel/src/Providers/RestClientProvider.cs

@@ -472,7 +472,8 @@ private static IReadOnlyList<ParameterProvider> BuildSpreadParametersForModel(In
                 var inputParameter = new InputParameter(
                     property.Name,
                     property.SerializedName,
-                    property.Description,
+                    property.Summary,
+                    property.Doc,
                     property.Type,
                     RequestLocation.Body,
                     null,

packages/http-client-csharp/generator/Microsoft.Generator.CSharp.ClientModel/src/Providers/ScmMethodProviderCollection.cs

@@ -14,6 +14,7 @@
 using Microsoft.Generator.CSharp.Providers;
 using Microsoft.Generator.CSharp.Snippets;
 using Microsoft.Generator.CSharp.Statements;
+using Microsoft.Generator.CSharp.Utilities;
 using static Microsoft.Generator.CSharp.Snippets.Snippet;
 
 namespace Microsoft.Generator.CSharp.ClientModel.Providers
@@ -71,7 +72,7 @@ private ScmMethodProvider BuildConvenienceMethod(MethodProvider protocolMethod,
 
             var methodSignature = new MethodSignature(
                 isAsync ? _cleanOperationName + "Async" : _cleanOperationName,
-                FormattableStringHelpers.FromString(Operation.Description),
+                DocHelpers.GetFormattableDescription(Operation.Summary, Operation.Doc) ?? FormattableStringHelpers.FromString(Operation.Name),
                 methodModifier,
                 GetResponseType(Operation.Responses, true, isAsync, out var responseBodyType),
                 null,
@@ -424,7 +425,7 @@ private ScmMethodProvider BuildProtocolMethod(MethodProvider createRequestMethod
 
             var methodSignature = new MethodSignature(
                 isAsync ? _cleanOperationName + "Async" : _cleanOperationName,
-                FormattableStringHelpers.FromString(Operation.Description),
+                DocHelpers.GetFormattableDescription(Operation.Summary, Operation.Doc) ?? FormattableStringHelpers.FromString(Operation.Name),
                 methodModifier,
                 GetResponseType(Operation.Responses, false, isAsync, out _),
                 $"The response returned from the service.",
@@ -450,7 +451,7 @@ private ScmMethodProvider BuildProtocolMethod(MethodProvider createRequestMethod
                     new XmlDocStatement("item", [], new XmlDocStatement("description", [$"This <see href=\"https://aka.ms/azsdk/net/protocol-methods\">protocol method</see> allows explicit creation of the request and processing of the response for advanced scenarios."]))
                 ];
                 XmlDocStatement listXmlDoc = new XmlDocStatement("<list type=\"bullet\">", "</list>", [], innerStatements: [.. listItems]);
-                protocolMethod.XmlDocs!.Summary = new XmlDocSummaryStatement([$"[Protocol Method] {Operation.Description}"], listXmlDoc);
+                protocolMethod.XmlDocs!.Summary = new XmlDocSummaryStatement([$"[Protocol Method] {DocHelpers.GetDescription(Operation.Summary, Operation.Doc) ?? Operation.Name}"], listXmlDoc);
             }
             return protocolMethod;
         }

packages/http-client-csharp/generator/Microsoft.Generator.CSharp.ClientModel/test/Providers/ClientProviders/ClientProviderSubClientTests.cs

@@ -14,11 +14,11 @@ namespace Microsoft.Generator.CSharp.ClientModel.Tests.Providers.ClientProviders
     public class ClientProviderSubClientTests
     {
         private const string TestClientName = "TestClient";
-        private static readonly InputClient _animalClient = new("animal", "AnimalClient description", [], [], TestClientName);
-        private static readonly InputClient _dogClient = new("dog", "DogClient description", [], [], _animalClient.Name);
-        private static readonly InputClient _catClient = new("cat", "CatClient description", [], [], _animalClient.Name);
-        private static readonly InputClient _hawkClient = new("hawkClient", "HawkClient description", [], [], _animalClient.Name);
-        private static readonly InputClient _huskyClient = new("husky", "HuskyClient description", [], [], _dogClient.Name);
+        private static readonly InputClient _animalClient = new("animal", string.Empty, "AnimalClient description", [], [], TestClientName);
+        private static readonly InputClient _dogClient = new("dog", string.Empty, "DogClient description", [], [], _animalClient.Name);
+        private static readonly InputClient _catClient = new("cat", string.Empty, "CatClient description", [], [], _animalClient.Name);
+        private static readonly InputClient _hawkClient = new("hawkClient", string.Empty, "HawkClient description", [], [], _animalClient.Name);
+        private static readonly InputClient _huskyClient = new("husky", string.Empty, "HuskyClient description", [], [], _dogClient.Name);
 
         [SetUp]
         public void SetUp()

packages/http-client-csharp/generator/Microsoft.Generator.CSharp.ClientModel/test/Providers/ClientProviders/ClientProviderTests.cs

@@ -23,9 +23,9 @@ public class ClientProviderTests
     {
         private const string SubClientsCategory = "WithSubClients";
         private const string TestClientName = "TestClient";
-        private static readonly InputClient _animalClient = new("animal", "AnimalClient description", [], [], TestClientName);
-        private static readonly InputClient _dogClient = new("dog", "DogClient description", [], [], _animalClient.Name);
-        private static readonly InputClient _huskyClient = new("husky", "HuskyClient description", [], [], _dogClient.Name);
+        private static readonly InputClient _animalClient = new("animal", "", "AnimalClient description", [], [], TestClientName);
+        private static readonly InputClient _dogClient = new("dog", "", "DogClient description", [], [], _animalClient.Name);
+        private static readonly InputClient _huskyClient = new("husky", "", "HuskyClient description", [], [], _dogClient.Name);
         private static readonly InputModelType _spreadModel = InputFactory.Model(
             "spreadModel",
             usage: InputModelTypeUsage.Spread,

packages/http-client-csharp/generator/Microsoft.Generator.CSharp.ClientModel/test/Providers/MrwSerializationTypeDefinitions/MrwSerializationTypeDefinitionTests.cs

@@ -690,10 +690,10 @@ public void TestIntSerializationStatement(
             var name = kind.ToString().ToLower();
             var properties = new List<InputModelProperty>
             {
-                new InputModelProperty("requiredInt", "requiredInt", "", new InputPrimitiveType(kind, name, $"TypeSpec.{name}", encode), true, false, false),
+                new InputModelProperty("requiredInt", "requiredInt", "", "", new InputPrimitiveType(kind, name, $"TypeSpec.{name}", encode), true, false, false),
              };
 
-            var inputModel = new InputModelType("TestModel", "TestModel", "public", null, "Test model.", InputModelTypeUsage.Input, properties, null, Array.Empty<InputModelType>(), null, null, new Dictionary<string, InputModelType>(), null, false);
+            var inputModel = new InputModelType("TestModel", "TestModel", "public", null, "", "Test model.", InputModelTypeUsage.Input, properties, null, Array.Empty<InputModelType>(), null, null, new Dictionary<string, InputModelType>(), null, false);
 
             var (_, serialization) = CreateModelAndSerialization(inputModel);
 

packages/http-client-csharp/generator/Microsoft.Generator.CSharp.Input/src/InputTypes/InputClient.cs

@@ -11,19 +11,21 @@ public class InputClient
         private readonly string? _key;
         private IReadOnlyDictionary<string, InputClientExample>? _examples;
 
-        public InputClient(string name, string description, IReadOnlyList<InputOperation> operations, IReadOnlyList<InputParameter> parameters, string? parent)
+        public InputClient(string name, string? summary, string? doc, IReadOnlyList<InputOperation> operations, IReadOnlyList<InputParameter> parameters, string? parent)
         {
             Name = name;
-            Description = description;
+            Summary = summary;
+            Doc = doc;
             Operations = operations;
             Parameters = parameters;
             Parent = parent;
         }
 
-        public InputClient() : this(string.Empty, string.Empty, Array.Empty<InputOperation>(), Array.Empty<InputParameter>(), null) { }
+        public InputClient() : this(string.Empty, string.Empty, string.Empty, Array.Empty<InputOperation>(), Array.Empty<InputParameter>(), null) { }
 
         public string Name { get; internal set; }
-        public string Description { get; internal set; }
+        public string? Summary { get; internal set; }
+        public string? Doc { get; internal set; }
         public IReadOnlyList<InputOperation> Operations { get; internal set; }
         public IReadOnlyList<InputParameter> Parameters { get; internal set; }
         public string? Parent { get; internal set; }