refactor(generator): split description into sumary and doc` (#5172)

* refactor(generator): split `description` into `sumary` and `doc` - update input types to replace `description` with `summary` and `doc` - update json converters for the emitter schema change - update test cases accordingly resolve #4771 --------- Co-authored-by: Mingzhe Huang (from Dev Box) <[email protected]>
Azure · Dec 18, 2024 · a7d1bd5 · a7d1bd5
1 parent 31f2a98
commit a7d1bd5
Show file tree

Hide file tree

Showing 241 changed files with 5,084 additions and 5,008 deletions.
diff --git a/package-lock.json b/package-lock.json
diff --git a/samples/AnomalyDetector/tspCodeModel.json b/samples/AnomalyDetector/tspCodeModel.json
diff --git a/src/AutoRest.CSharp/Common/Input/CodeModelConverter.cs b/src/AutoRest.CSharp/Common/Input/CodeModelConverter.cs
@@ -71,7 +71,8 @@ private IReadOnlyList<InputClient> CreateClients(IEnumerable<OperationGroup> ope
         private InputClient CreateClient(OperationGroup operationGroup, Dictionary<ServiceRequest, InputOperation>? serviceRequestToInputOperation, Dictionary<InputOperation, Operation>? inputOperationToOperation)
             => new(
                 Name: operationGroup.Language.Default.Name,
-                Description: operationGroup.Language.Default.Description,
+                Summary: string.Empty,
+                Doc: operationGroup.Language.Default.Description,
                 Operations: CreateOperations(operationGroup.Operations, serviceRequestToInputOperation, inputOperationToOperation),
                 Parameters: Array.Empty<InputParameter>(),
                 Parent: null)
@@ -136,10 +137,10 @@ private InputOperation CreateOperation(ServiceRequest serviceRequest, Operation
             var inputOperation = new InputOperation(
                 name: operation.Language.Default.Name,
                 // Keep the behavior for non-mgmt scenarios
-                resourceName: Configuration.AzureArm ? GetResoureName(operationId) : null,
+                resourceName: Configuration.AzureArm ? GetResourceName(operationId) : null,
                 summary: operation.Language.Default.Summary,
                 deprecated: operation.Deprecated?.Reason,
-                description: operation.Language.Default.Description,
+                doc: operation.Language.Default.Description,
                 accessibility: operation.Accessibility,
                 parameters: parameters,
                 responses: operation.Responses.Select<ServiceResponse, OperationResponse>(CreateOperationResponse).ToList(),
@@ -163,7 +164,7 @@ private InputOperation CreateOperation(ServiceRequest serviceRequest, Operation
             return inputOperation;
         }
 
-        private static string? GetResoureName(string? operationId)
+        private static string? GetResourceName(string? operationId)
         {
             if (operationId is null || operationId.IndexOf("_") == -1)
             {
@@ -300,7 +301,8 @@ private List<InputParameter> CreateOperationParameters(IReadOnlyCollection<Reque
         private InputParameter CreateOperationParameter(RequestParameter input) => new(
             Name: input.Language.Default.Name,
             NameInRequest: input.Language.Default.SerializedName ?? input.Language.Default.Name,
-            Description: input.Language.Default.Description,
+            Summary: string.Empty,
+            Doc: input.Language.Default.Description,
             Type: GetOrCreateType(input),
             Location: GetRequestLocation(input),
             DefaultValue: GetDefaultValue(input),
@@ -332,7 +334,8 @@ private List<InputParameter> CreateOperationParameters(IReadOnlyCollection<Reque
         private OperationResponseHeader CreateResponseHeader(HttpResponseHeader header) => new(
             Name: header.CSharpName(),
             NameInResponse: header.Extensions?.HeaderCollectionPrefix ?? header.Header,
-            Description: header.Language.Default.Description,
+            Summary: string.Empty,
+            Doc: header.Language.Default.Description,
             Type: GetOrCreateType(header.Schema, header.Extensions?.Format, true)
         );
 
@@ -453,7 +456,8 @@ private InputModelType GetOrCreateModel(ObjectSchema schema)
                 CrossLanguageDefinitionId: GetCrossLanguageDefinitionId(schema),
                 Access: schema.Extensions?.Accessibility ?? (usage.HasFlag(SchemaTypeUsage.Model) ? "public" : "internal"),
                 Deprecation: schema.Deprecated?.Reason,
-                Description: schema.CreateDescription(),
+                Summary: string.Empty,
+                Doc: schema.CreateDescription(),
                 Usage: (schema.Extensions != null && schema.Extensions.Formats.Contains("multipart/form-data") ? InputModelTypeUsage.MultipartFormData : InputModelTypeUsage.None)
                         | GetUsage(usage),
                 Properties: properties,
@@ -504,7 +508,8 @@ private InputModelProperty GetOrCreateProperty(Property property)
             inputProperty = new(
                 Name: property.Language.Default.Name,
                 SerializedName: property.SerializedName,
-                Description: property.Language.Default.Description,
+                Summary: string.Empty,
+                Doc: property.Language.Default.Description,
                 Type: GetOrCreateType(property),
                 ConstantValue: property.Schema is ConstantSchema constantSchema ? CreateConstant(constantSchema, constantSchema.Extensions?.Format, property.IsNullable) : null,
                 IsRequired: property.IsRequired,
@@ -765,7 +770,7 @@ private InputType CreateTypeForObjectSchema(ObjectSchema objectSchema)
         }
 
         private static InputType CreateDataFactoryElementInputType(bool isNullable, InputType argumentType)
-            => new InputModelType("DataFactoryElement", "Azure.Core.Resources.DataFactoryElement", null, null, null, InputModelTypeUsage.None, Array.Empty<InputModelProperty>(), null, Array.Empty<InputModelType>(), null, null, new Dictionary<string, InputModelType>(), null, new List<InputType> { argumentType }).WithNullable(isNullable);
+            => new InputModelType("DataFactoryElement", "Azure.Core.Resources.DataFactoryElement", null, null, null, null, InputModelTypeUsage.None, Array.Empty<InputModelProperty>(), null, Array.Empty<InputModelType>(), null, null, new Dictionary<string, InputModelType>(), null, new List<InputType> { argumentType }).WithNullable(isNullable);
 
         private InputConstant CreateConstant(ConstantSchema constantSchema, string? format, bool isNullable)
         {
@@ -806,7 +811,8 @@ private InputEnumType CreateEnumType(Schema schema, PrimitiveSchema choiceType,
                 CrossLanguageDefinitionId: GetCrossLanguageDefinitionId(schema),
                 Accessibility: schema.Extensions?.Accessibility ?? (usage.HasFlag(SchemaTypeUsage.Model) ? "public" : "internal"),
                 Deprecated: schema.Deprecated?.Reason,
-                Description: schema.CreateDescription(),
+                Summary: string.Empty,
+                Doc: schema.CreateDescription(),
                 Usage: GetUsage(usage),
                 ValueType: valueType,
                 Values: choices.Select(c => CreateEnumValue(c, valueType)).ToList(),
@@ -836,7 +842,8 @@ private static InputEnumTypeValue CreateEnumValue(ChoiceValue choiceValue, Input
             var value = ConvertRawValue(valueType, choiceValue.Value);
             return new(
                 Name: choiceValue.Language.Default.Name,
-                Description: choiceValue.Language.Default.Description,
+                Summary: string.Empty,
+                Doc: choiceValue.Language.Default.Description,
                 Value: value!);
         }
 

diff --git a/src/AutoRest.CSharp/Common/Input/InputTypes/InputClient.cs b/src/AutoRest.CSharp/Common/Input/InputTypes/InputClient.cs
@@ -6,7 +6,7 @@
 
 namespace AutoRest.CSharp.Common.Input;
 
-internal record InputClient(string Name, string Description, IReadOnlyList<InputOperation> Operations, IReadOnlyList<InputParameter> Parameters, string? Parent)
+internal record InputClient(string Name, string? Summary, string? Doc, IReadOnlyList<InputOperation> Operations, IReadOnlyList<InputParameter> Parameters, string? Parent)
 {
     private readonly string? _key;
 
@@ -19,5 +19,5 @@ public string Key
     public IReadOnlyList<InputOperation> Operations { get; internal set; } = Operations ?? Array.Empty<InputOperation>();
     public IReadOnlyList<InputDecoratorInfo> Decorators { get; internal set; } = new List<InputDecoratorInfo>();
 
-    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) { }
 }
diff --git a/src/AutoRest.CSharp/Common/Input/InputTypes/InputEnumType.cs b/src/AutoRest.CSharp/Common/Input/InputTypes/InputEnumType.cs
@@ -5,5 +5,5 @@
 
 namespace AutoRest.CSharp.Common.Input;
 
-internal record InputEnumType(string Name, string CrossLanguageDefinitionId, string? Accessibility, string? Deprecated, string Description, InputModelTypeUsage Usage, InputPrimitiveType ValueType, IReadOnlyList<InputEnumTypeValue> Values, bool IsExtensible)
+internal record InputEnumType(string Name, string CrossLanguageDefinitionId, string? Accessibility, string? Deprecated, string? Summary, string? Doc, InputModelTypeUsage Usage, InputPrimitiveType ValueType, IReadOnlyList<InputEnumTypeValue> Values, bool IsExtensible)
     : InputType(Name);
diff --git a/src/AutoRest.CSharp/Common/Input/InputTypes/InputEnumTypeFloatValue.cs b/src/AutoRest.CSharp/Common/Input/InputTypes/InputEnumTypeFloatValue.cs
@@ -3,4 +3,4 @@
 
 namespace AutoRest.CSharp.Common.Input;
 
-internal record InputEnumTypeFloatValue(string Name, float FloatValue, string? Description) : InputEnumTypeValue(Name, FloatValue, Description);
+internal record InputEnumTypeFloatValue(string Name, float FloatValue, string? Summary, string? Doc) : InputEnumTypeValue(Name, FloatValue, Summary, Doc);
diff --git a/src/AutoRest.CSharp/Common/Input/InputTypes/InputEnumTypeIntegerValue.cs b/src/AutoRest.CSharp/Common/Input/InputTypes/InputEnumTypeIntegerValue.cs
@@ -3,4 +3,4 @@
 
 namespace AutoRest.CSharp.Common.Input;
 
-internal record InputEnumTypeIntegerValue(string Name, int IntegerValue, string? Description) : InputEnumTypeValue(Name, IntegerValue, Description);
+internal record InputEnumTypeIntegerValue(string Name, int IntegerValue, string? Summary, string? Doc) : InputEnumTypeValue(Name, IntegerValue, Summary, Doc);
diff --git a/src/AutoRest.CSharp/Common/Input/InputTypes/InputEnumTypeStringValue.cs b/src/AutoRest.CSharp/Common/Input/InputTypes/InputEnumTypeStringValue.cs
@@ -3,4 +3,4 @@
 
 namespace AutoRest.CSharp.Common.Input;
 
-internal record InputEnumTypeStringValue(string Name, string StringValue, string? Description) : InputEnumTypeValue(Name, StringValue, Description);
+internal record InputEnumTypeStringValue(string Name, string StringValue, string? Summary, string? Doc) : InputEnumTypeValue(Name, StringValue, Summary, Doc);
diff --git a/src/AutoRest.CSharp/Common/Input/InputTypes/InputEnumTypeValue.cs b/src/AutoRest.CSharp/Common/Input/InputTypes/InputEnumTypeValue.cs
@@ -5,7 +5,7 @@
 
 namespace AutoRest.CSharp.Common.Input;
 
-internal record InputEnumTypeValue(string Name, object Value, string? Description)
+internal record InputEnumTypeValue(string Name, object Value, string? Summary, string? Doc)
 {
     public virtual string GetJsonValueString() => GetValueString();
     public string GetValueString() => (Value.ToString() ?? string.Empty);

diff --git a/src/AutoRest.CSharp/Common/Input/InputTypes/InputModelProperty.cs b/src/AutoRest.CSharp/Common/Input/InputTypes/InputModelProperty.cs
@@ -6,7 +6,7 @@
 
 namespace AutoRest.CSharp.Common.Input;
 
-internal record InputModelProperty(string Name, string SerializedName, string Description, InputType Type, InputConstant? ConstantValue, bool IsRequired, bool IsReadOnly, bool IsDiscriminator)
+internal record InputModelProperty(string Name, string SerializedName, string? Summary, string? Doc, InputType Type, InputConstant? ConstantValue, bool IsRequired, bool IsReadOnly, bool IsDiscriminator)
 {
     public FormattableString? DefaultValue { get; init; }
 

diff --git a/src/AutoRest.CSharp/Common/Input/InputTypes/InputModelType.cs b/src/AutoRest.CSharp/Common/Input/InputTypes/InputModelType.cs
@@ -10,7 +10,7 @@
 
 namespace AutoRest.CSharp.Common.Input
 {
-    internal record InputModelType(string Name, string CrossLanguageDefinitionId, string? Access, string? Deprecation, string? Description, InputModelTypeUsage Usage, IReadOnlyList<InputModelProperty> Properties, InputModelType? BaseModel, IReadOnlyList<InputModelType> DerivedModels, string? DiscriminatorValue, InputModelProperty? DiscriminatorProperty, IReadOnlyDictionary<string, InputModelType> DiscriminatedSubtypes, InputType? AdditionalProperties, IReadOnlyList<InputType>? ArgumentTypes = null)
+    internal record InputModelType(string Name, string CrossLanguageDefinitionId, string? Access, string? Deprecation, string? Summary, string? Doc, InputModelTypeUsage Usage, IReadOnlyList<InputModelProperty> Properties, InputModelType? BaseModel, IReadOnlyList<InputModelType> DerivedModels, string? DiscriminatorValue, InputModelProperty? DiscriminatorProperty, IReadOnlyDictionary<string, InputModelType> DiscriminatedSubtypes, InputType? AdditionalProperties, IReadOnlyList<InputType>? ArgumentTypes = null)
         : InputType(Name)
     {
         /// <summary>

diff --git a/src/AutoRest.CSharp/Common/Input/InputTypes/InputOperation.cs b/src/AutoRest.CSharp/Common/Input/InputTypes/InputOperation.cs
@@ -7,6 +7,7 @@
 using AutoRest.CSharp.Common.Input.Examples;
 using AutoRest.CSharp.Utilities;
 using Azure.Core;
+using Humanizer;
 
 namespace AutoRest.CSharp.Common.Input;
 
@@ -17,7 +18,7 @@ public InputOperation(
     string? resourceName,
     string? summary,
     string? deprecated,
-    string description,
+    string? doc,
     string? accessibility,
     IReadOnlyList<InputParameter> parameters,
     IReadOnlyList<OperationResponse> responses,
@@ -41,7 +42,7 @@ public InputOperation(
         ResourceName = resourceName;
         Summary = summary;
         Deprecated = deprecated;
-        Description = description;
+        Doc = doc;
         Accessibility = accessibility;
         Parameters = parameters;
         Responses = responses;
@@ -66,7 +67,7 @@ public InputOperation() : this(
         resourceName: null,
         summary: null,
         deprecated: null,
-        description: string.Empty,
+        doc: string.Empty,
         accessibility: null,
         parameters: Array.Empty<InputParameter>(),
         responses: Array.Empty<OperationResponse>(),
@@ -94,7 +95,7 @@ public static InputOperation RemoveApiVersionParam(InputOperation operation)
             operation.ResourceName,
             operation.Summary,
             operation.Deprecated,
-            operation.Description,
+            operation.Doc,
             operation.Accessibility,
             operation.Parameters.Where(p => !p.IsApiVersion).ToList(),
             operation.Responses,
@@ -138,7 +139,7 @@ private IReadOnlyList<InputOperationExample> EnsureExamples()
     public string? ResourceName { get; }
     public string? Summary { get; }
     public string? Deprecated { get; }
-    public string Description { get; }
+    public string? Doc { get; }
     public string? Accessibility { get; }
     public IReadOnlyList<InputParameter> Parameters { get; init; }
     public IReadOnlyList<OperationResponse> Responses { get; }
@@ -164,4 +165,5 @@ private IReadOnlyList<InputOperationExample> EnsureExamples()
     internal string SpecName { get; init; }
 
     internal bool IsNameChanged { get; init; }
-}
+    public string DocDescription => Doc ?? $"{Name.Humanize()}.";
+};
diff --git a/src/AutoRest.CSharp/Common/Input/InputTypes/InputParameter.cs b/src/AutoRest.CSharp/Common/Input/InputTypes/InputParameter.cs
@@ -8,7 +8,8 @@ namespace AutoRest.CSharp.Common.Input;
 internal record InputParameter(
     string Name,
     string NameInRequest,
-    string? Description,
+    string? Summary,
+    string? Doc,
     InputType Type,
     RequestLocation Location,
     InputConstant? DefaultValue,
@@ -29,7 +30,8 @@ internal record InputParameter(
     public InputParameter() : this(
         Name: string.Empty,
         NameInRequest: string.Empty,
-        Description: null,
+        Summary: null,
+        Doc: null,
         Type: InputPrimitiveType.Unknown,
         Location: RequestLocation.None,
         DefaultValue: null,

diff --git a/src/AutoRest.CSharp/Common/Input/InputTypes/OperationResponseHeader.cs b/src/AutoRest.CSharp/Common/Input/InputTypes/OperationResponseHeader.cs
@@ -6,7 +6,7 @@
 
 namespace AutoRest.CSharp.Common.Input;
 
-internal record OperationResponseHeader(string Name, string NameInResponse, string Description, InputType Type)
+internal record OperationResponseHeader(string Name, string NameInResponse, string? Summary, string? Doc, InputType Type)
 {
-    public OperationResponseHeader() : this("", "", "", InputPrimitiveType.String) { }
+    public OperationResponseHeader() : this(string.Empty, string.Empty, string.Empty, string.Empty, InputPrimitiveType.String) { }
 }
diff --git a/src/AutoRest.CSharp/Common/Input/InputTypes/Serialization/TypeSpecInputClientConverter.cs b/src/AutoRest.CSharp/Common/Input/InputTypes/Serialization/TypeSpecInputClientConverter.cs
@@ -28,7 +28,8 @@ public override void Write(Utf8JsonWriter writer, InputClient value, JsonSeriali
         {
             var isFirstProperty = id == null;
             string? name = null;
-            string? description = null;
+            string? summary = null;
+            string? doc = null;
             IReadOnlyList<InputOperation>? operations = null;
             IReadOnlyList<InputParameter>? parameters = null;
             string? parent = null;
@@ -37,7 +38,8 @@ public override void Write(Utf8JsonWriter writer, InputClient value, JsonSeriali
             {
                 var isKnownProperty = reader.TryReadReferenceId(ref isFirstProperty, ref id)
                     || reader.TryReadString(nameof(InputClient.Name), ref name)
-                    || reader.TryReadString(nameof(InputClient.Description), ref description)
+                    || reader.TryReadString("Summary", ref summary)
+                    || reader.TryReadString("Doc", ref doc)
                     || reader.TryReadWithConverter(nameof(InputClient.Operations), options, ref operations)
                     || reader.TryReadWithConverter(nameof(InputClient.Parameters), options, ref parameters)
                     || reader.TryReadString(nameof(InputClient.Parent), ref parent);
@@ -49,10 +51,9 @@ public override void Write(Utf8JsonWriter writer, InputClient value, JsonSeriali
             }
 
             name= name ?? throw new JsonException("InputClient must have name");
-            description = description ?? string.Empty;
             operations = operations ?? Array.Empty<InputOperation>();
             parameters = parameters ?? Array.Empty<InputParameter>();
-            var inputClient = new InputClient(name, description, operations, parameters, parent);
+            var inputClient = new InputClient(name, summary, doc, operations, parameters, parent);
             if (id != null)
             {
                 resolver.AddReference(id, inputClient);
Original file line number	Diff line number	Diff line change
Expand Up		@@ -3,4 +3,4 @@

		namespace AutoRest.CSharp.Common.Input;

		internal record InputEnumTypeFloatValue(string Name, float FloatValue, string? Description) : InputEnumTypeValue(Name, FloatValue, Description);
		internal record InputEnumTypeFloatValue(string Name, float FloatValue, string? Summary, string? Doc) : InputEnumTypeValue(Name, FloatValue, Summary, Doc);