From 6f9aac874b94a583673dffdc70f520ade5633d76 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Tue, 30 Jan 2024 16:05:33 -0500 Subject: [PATCH 01/21] - adds templating mechanism for descriptions --- src/Kiota.Builder/CodeDOM/CodeConstant.cs | 8 +- .../CodeDOM/CodeDocumentation.cs | 27 +++++- src/Kiota.Builder/KiotaBuilder.cs | 84 +++++++++---------- .../Refiners/CommonLanguageRefiner.cs | 26 +++--- src/Kiota.Builder/Refiners/GoRefiner.cs | 4 +- src/Kiota.Builder/Refiners/JavaRefiner.cs | 4 +- src/Kiota.Builder/Refiners/PhpRefiner.cs | 6 +- src/Kiota.Builder/Refiners/PythonRefiner.cs | 2 +- src/Kiota.Builder/Refiners/SwiftRefiner.cs | 2 +- .../Refiners/TypeScriptRefiner.cs | 2 +- .../Writers/CLI/CliCodeMethodWriter.cs | 2 +- .../Writers/CSharp/CSharpConventionService.cs | 2 +- .../Writers/CSharp/CodeEnumWriter.cs | 4 +- .../Writers/CSharp/CodeIndexerWriter.cs | 4 +- .../Writers/CSharp/CodeMethodWriter.cs | 2 +- .../Writers/CSharp/CodePropertyWriter.cs | 2 +- .../Writers/Go/CodeClassDeclarationWriter.cs | 2 +- .../Writers/Go/CodeEnumWriter.cs | 6 +- .../Go/CodeInterfaceDeclarationWriter.cs | 2 +- .../Writers/Go/CodeMethodWriter.cs | 2 +- .../Writers/Go/CodePropertyWriter.cs | 2 +- .../Writers/Java/CodeEnumWriter.cs | 2 +- .../Writers/Java/CodeMethodWriter.cs | 2 +- .../Writers/Java/JavaConventionService.cs | 2 +- .../Writers/Php/CodeMethodWriter.cs | 6 +- .../Writers/Php/CodePropertyWriter.cs | 4 +- .../Writers/Php/PhpConventionService.cs | 2 +- .../Writers/Python/CodeEnumWriter.cs | 2 +- .../Writers/Python/CodeMethodWriter.cs | 8 +- .../Writers/Python/CodePropertyWriter.cs | 2 +- .../Writers/Python/PythonConventionService.cs | 2 +- .../Ruby/CodeClassDeclarationWriter.cs | 2 +- .../Writers/Ruby/CodeEnumWriter.cs | 2 +- .../Writers/Ruby/CodeMethodWriter.cs | 8 +- .../Writers/Ruby/CodePropertyWriter.cs | 2 +- .../Swift/CodeClassDeclarationWriter.cs | 2 +- .../Writers/TypeScript/CodeConstantWriter.cs | 2 +- .../Writers/TypeScript/CodeMethodWriter.cs | 2 +- .../TypeScript/TypeScriptConventionService.cs | 2 +- .../CodeDOM/CodeEnumTests.cs | 2 +- .../CodeDOM/CodeIndexerTests.cs | 2 +- .../Kiota.Builder.Tests/KiotaBuilderTests.cs | 34 ++++---- .../Refiners/CSharpLanguageRefinerTests.cs | 2 +- .../Refiners/GoLanguageRefinerTests.cs | 2 +- .../Refiners/JavaLanguageRefinerTests.cs | 2 +- .../Refiners/PythonLanguageRefinerTests.cs | 2 +- .../Refiners/RubyLanguageRefinerTests.cs | 2 +- .../TypeScriptLanguageRefinerTests.cs | 2 +- .../Writers/CLI/CliCodeMethodWriterTests.cs | 22 ++--- .../Writers/CSharp/CodeEnumWriterTests.cs | 4 +- .../Writers/CSharp/CodeIndexerWriterTests.cs | 2 +- .../Writers/CSharp/CodeMethodWriterTests.cs | 12 +-- .../Writers/Go/CodeEnumWriterTests.cs | 4 +- .../Writers/Go/CodeMethodWriterTests.cs | 10 +-- .../Writers/Java/CodeEnumWriterTests.cs | 4 +- .../Writers/Java/CodeMethodWriterTests.cs | 8 +- .../Php/CodeClassDeclarationWriterTests.cs | 10 +-- .../Writers/Php/CodeMethodWriterTests.cs | 54 ++++++------ .../Writers/Php/CodePropertyWriterTests.cs | 6 +- .../Writers/Python/CodeMethodWriterTests.cs | 24 +++--- .../Writers/Python/CodePropertyWriterTests.cs | 4 +- .../Writers/Ruby/CodeMethodWriterTests.cs | 4 +- .../TypeScript/CodeConstantWriterTests.cs | 4 +- .../TypeScript/CodeFunctionWriterTests.cs | 12 +-- 64 files changed, 252 insertions(+), 231 deletions(-) diff --git a/src/Kiota.Builder/CodeDOM/CodeConstant.cs b/src/Kiota.Builder/CodeDOM/CodeConstant.cs index 0d6ff8ed76..96d8eb93b1 100644 --- a/src/Kiota.Builder/CodeDOM/CodeConstant.cs +++ b/src/Kiota.Builder/CodeDOM/CodeConstant.cs @@ -35,7 +35,7 @@ public CodeDocumentation Documentation Kind = CodeConstantKind.QueryParametersMapper, OriginalCodeElement = source, }; - result.Documentation.Description = "Mapper for query parameters from symbol name to serialization name represented as a constant."; + result.Documentation.DescriptionTemplate = "Mapper for query parameters from symbol name to serialization name represented as a constant."; return result; } public static CodeConstant? FromCodeEnum(CodeEnum source) @@ -63,7 +63,7 @@ public CodeDocumentation Documentation UriTemplate = urlTemplateProperty.DefaultValue, OriginalCodeElement = codeClass }; - result.Documentation.Description = "Uri template for the request builder."; + result.Documentation.DescriptionTemplate = "Uri template for the request builder."; return result; } public static CodeConstant? FromRequestBuilderToNavigationMetadata(CodeClass codeClass, CodeUsing[]? usingsToAdd = default) @@ -79,7 +79,7 @@ public CodeDocumentation Documentation Kind = CodeConstantKind.NavigationMetadata, OriginalCodeElement = codeClass, }; - result.Documentation.Description = "Metadata for all the navigation properties in the request builder."; + result.Documentation.DescriptionTemplate = "Metadata for all the navigation properties in the request builder."; if (usingsToAdd is { Length: > 0 } usingsToAddList) result.AddUsing(usingsToAddList); return result; @@ -96,7 +96,7 @@ public CodeDocumentation Documentation Kind = CodeConstantKind.RequestsMetadata, OriginalCodeElement = codeClass, }; - result.Documentation.Description = "Metadata for all the requests in the request builder."; + result.Documentation.DescriptionTemplate = "Metadata for all the requests in the request builder."; if (usingsToAdd is { Length: > 0 } usingsToAddList) result.AddUsing(usingsToAddList); return result; diff --git a/src/Kiota.Builder/CodeDOM/CodeDocumentation.cs b/src/Kiota.Builder/CodeDOM/CodeDocumentation.cs index c14c37abb0..a1aa5e095a 100644 --- a/src/Kiota.Builder/CodeDOM/CodeDocumentation.cs +++ b/src/Kiota.Builder/CodeDOM/CodeDocumentation.cs @@ -1,4 +1,5 @@ using System; +using System.Collections.Concurrent; namespace Kiota.Builder.CodeDOM; @@ -10,7 +11,7 @@ public class CodeDocumentation : ICloneable /// /// The description of the current element. /// - public string Description + public string DescriptionTemplate { get; set; } = string.Empty; @@ -34,14 +35,34 @@ public object Clone() { return new CodeDocumentation { - Description = Description, + DescriptionTemplate = DescriptionTemplate, DocumentationLink = DocumentationLink == null ? null : new(DocumentationLink.ToString()), DocumentationLabel = DocumentationLabel, + TypeReferences = new(TypeReferences, StringComparer.OrdinalIgnoreCase) }; } + /// + /// References to be resolved when the description is emitted. + /// Keys MUST match the description template tokens or they will be ignored. + /// + public ConcurrentDictionary TypeReferences { get; private set; } = new(StringComparer.OrdinalIgnoreCase); + public string GetDescription(Func typeReferenceResolver) + { + ArgumentNullException.ThrowIfNull(typeReferenceResolver); + if (string.IsNullOrEmpty(DescriptionTemplate)) + return string.Empty; + var description = DescriptionTemplate; + foreach (var (key, value) in TypeReferences) + { + var resolvedValue = typeReferenceResolver(value); + if (!string.IsNullOrEmpty(resolvedValue)) + description = description.Replace($"{{{key}}}", resolvedValue, StringComparison.OrdinalIgnoreCase); + } + return description; + } public bool DescriptionAvailable { - get => !string.IsNullOrEmpty(Description); + get => !string.IsNullOrEmpty(DescriptionTemplate); } public bool ExternalDocumentationAvailable { diff --git a/src/Kiota.Builder/KiotaBuilder.cs b/src/Kiota.Builder/KiotaBuilder.cs index a001466ca7..a704bb096b 100644 --- a/src/Kiota.Builder/KiotaBuilder.cs +++ b/src/Kiota.Builder/KiotaBuilder.cs @@ -714,7 +714,7 @@ private void CreateRequestBuilderClass(CodeNamespace currentNamespace, OpenApiUr Kind = CodeClassKind.RequestBuilder, Documentation = new() { - Description = "The main entry point of the SDK, exposes the configuration and the fluent API." + DescriptionTemplate = "The main entry point of the SDK, exposes the configuration and the fluent API." }, }).First(); else @@ -727,7 +727,7 @@ private void CreateRequestBuilderClass(CodeNamespace currentNamespace, OpenApiUr Kind = CodeClassKind.RequestBuilder, Documentation = new() { - Description = currentNode.GetPathItemDescription(Constants.DefaultOpenApiLabel, $"Builds and executes requests for operations under {currentNode.Path}"), + DescriptionTemplate = currentNode.GetPathItemDescription(Constants.DefaultOpenApiLabel, $"Builds and executes requests for operations under {currentNode.Path}"), }, }).First(); } @@ -759,7 +759,7 @@ private void CreateRequestBuilderClass(CodeNamespace currentNamespace, OpenApiUr prop.Deprecation = currentNode.GetDeprecationInformation(); if (!string.IsNullOrWhiteSpace(description)) { - prop.Documentation.Description = description; + prop.Documentation.DescriptionTemplate = description; } codeClass.AddProperty(prop); } @@ -796,7 +796,7 @@ private static void CreateWithUrlMethod(OpenApiUrlTreeNode currentNode, CodeClas Kind = CodeMethodKind.RawUrlBuilder, Documentation = new() { - Description = "Returns a request builder with the provided arbitrary URL. Using this method means any other path or query parameters are ignored.", + DescriptionTemplate = "Returns a request builder with the provided arbitrary URL. Using this method means any other path or query parameters are ignored.", }, Access = AccessModifier.Public, IsAsync = false, @@ -817,7 +817,7 @@ private static void CreateWithUrlMethod(OpenApiUrlTreeNode currentNode, CodeClas Optional = false, Documentation = new() { - Description = "The raw URL to use for the request builder.", + DescriptionTemplate = "The raw URL to use for the request builder.", }, Kind = CodeParameterKind.RawUrl, }); @@ -831,7 +831,7 @@ private static void CreateMethod(string propIdentifier, string propType, CodeCla Kind = CodeMethodKind.RequestBuilderWithParameters, Documentation = new() { - Description = currentNode.GetPathItemDescription(Constants.DefaultOpenApiLabel, $"Builds and executes requests for operations under {currentNode.Path}"), + DescriptionTemplate = currentNode.GetPathItemDescription(Constants.DefaultOpenApiLabel, $"Builds and executes requests for operations under {currentNode.Path}"), }, Access = AccessModifier.Public, IsAsync = false, @@ -868,7 +868,7 @@ private static void AddPathParametersToMethod(OpenApiUrlTreeNode currentNode, Co Optional = asOptional, Documentation = new() { - Description = parameter.Description.CleanupDescription(), + DescriptionTemplate = parameter.Description.CleanupDescription(), }, Kind = CodeParameterKind.Path, SerializationName = parameter.Name.Equals(codeName, StringComparison.OrdinalIgnoreCase) ? string.Empty : parameter.Name.SanitizeParameterNameForUrlTemplate(), @@ -890,7 +890,7 @@ private void CreateUrlManagement(CodeClass currentClass, OpenApiUrlTreeNode curr ReadOnly = true, Documentation = new() { - Description = "Url template to use to build the URL for the current request builder", + DescriptionTemplate = "Url template to use to build the URL for the current request builder", }, Kind = CodePropertyKind.UrlTemplate, Type = new CodeType @@ -907,7 +907,7 @@ private void CreateUrlManagement(CodeClass currentClass, OpenApiUrlTreeNode curr Name = RequestAdapterParameterName, Documentation = new() { - Description = "The request adapter to use to execute the requests.", + DescriptionTemplate = "The request adapter to use to execute the requests.", }, Kind = CodePropertyKind.RequestAdapter, Access = AccessModifier.Private, @@ -928,7 +928,7 @@ private void CreateUrlManagement(CodeClass currentClass, OpenApiUrlTreeNode curr IsStatic = false, Documentation = new() { - Description = $"Instantiates a new {currentClass.Name.ToFirstCharacterUpperCase()} and sets the default values.", + DescriptionTemplate = $"Instantiates a new {currentClass.Name.ToFirstCharacterUpperCase()} and sets the default values.", }, Access = AccessModifier.Public, ReturnType = new CodeType { Name = VoidType, IsExternal = true }, @@ -939,7 +939,7 @@ private void CreateUrlManagement(CodeClass currentClass, OpenApiUrlTreeNode curr Name = PathParametersParameterName, Documentation = new() { - Description = "Path parameters for the request", + DescriptionTemplate = "Path parameters for the request", }, Kind = CodePropertyKind.PathParameters, Access = AccessModifier.Private, @@ -988,7 +988,7 @@ private void CreateUrlManagement(CodeClass currentClass, OpenApiUrlTreeNode curr Optional = true, Documentation = new() { - Description = "The backing store to use for the models.", + DescriptionTemplate = "The backing store to use for the models.", }, Kind = CodeParameterKind.BackingStore, Type = new CodeType @@ -1013,7 +1013,7 @@ private void CreateUrlManagement(CodeClass currentClass, OpenApiUrlTreeNode curr Optional = false, Documentation = new() { - Description = "The raw URL to use for the request builder.", + DescriptionTemplate = "The raw URL to use for the request builder.", }, Kind = CodeParameterKind.RawUrl, }); @@ -1124,7 +1124,7 @@ private CodeParameter GetIndexerParameter(OpenApiUrlTreeNode currentNode, OpenAp Name = segment.CleanupSymbolName(), Documentation = new() { - Description = parameter?.Description.CleanupDescription() is string description && !string.IsNullOrEmpty(description) ? description : "Unique identifier of the item", + DescriptionTemplate = parameter?.Description.CleanupDescription() is string description && !string.IsNullOrEmpty(description) ? description : "Unique identifier of the item", }, }; return result; @@ -1153,7 +1153,7 @@ private CodeIndexer[] CreateIndexer(string childIdentifier, string childType, Co Name = childIdentifier, Documentation = new() { - Description = currentNode.GetPathItemDescription(Constants.DefaultOpenApiLabel, $"Gets an item from the {currentNode.GetNodeNamespaceFromPath(config.ClientNamespaceName)} collection"), + DescriptionTemplate = currentNode.GetPathItemDescription(Constants.DefaultOpenApiLabel, $"Gets an item from the {currentNode.GetNodeNamespaceFromPath(config.ClientNamespaceName)} collection"), }, ReturnType = new CodeType { Name = childType }, PathSegment = parentNode.GetNodeNamespaceFromPath(string.Empty).Split('.')[^1], @@ -1189,7 +1189,7 @@ private CodeIndexer[] CreateIndexer(string childIdentifier, string childType, Co Kind = kind, Documentation = new() { - Description = propertySchema?.Description.CleanupDescription() is string description && !string.IsNullOrEmpty(description) ? + DescriptionTemplate = propertySchema?.Description.CleanupDescription() is string description && !string.IsNullOrEmpty(description) ? description : $"The {propertyName} property", }, @@ -1396,7 +1396,7 @@ private void CreateOperationMethods(OpenApiUrlTreeNode currentNode, OperationTyp Kind = CodeClassKind.RequestConfiguration, Documentation = new() { - Description = "Configuration for the request such as headers, query parameters, and middleware options.", + DescriptionTemplate = "Configuration for the request such as headers, query parameters, and middleware options.", }, }).First(); @@ -1414,7 +1414,7 @@ private void CreateOperationMethods(OpenApiUrlTreeNode currentNode, OperationTyp { DocumentationLink = operation.ExternalDocs?.Url, DocumentationLabel = operation.ExternalDocs?.Description ?? string.Empty, - Description = (operation.Description is string description && !string.IsNullOrEmpty(description) ? + DescriptionTemplate = (operation.Description is string description && !string.IsNullOrEmpty(description) ? description : operation.Summary) .CleanupDescription(), @@ -1445,7 +1445,7 @@ private void CreateOperationMethods(OpenApiUrlTreeNode currentNode, OperationTyp Kind = CodeParameterKind.Cancellation, Documentation = new() { - Description = "Cancellation token to use when cancelling requests", + DescriptionTemplate = "Cancellation token to use when cancelling requests", }, Type = new CodeType { Name = "CancellationToken", IsExternal = true }, }; @@ -1471,7 +1471,7 @@ private void CreateOperationMethods(OpenApiUrlTreeNode currentNode, OperationTyp HttpMethod = method, Documentation = new() { - Description = (operation.Description ?? operation.Summary).CleanupDescription(), + DescriptionTemplate = (operation.Description ?? operation.Summary).CleanupDescription(), }, ReturnType = new CodeType { Name = "RequestInformation", IsNullable = false, IsExternal = true }, Parent = parentClass, @@ -1514,7 +1514,7 @@ private void CreateOperationMethods(OpenApiUrlTreeNode currentNode, OperationTyp Type = x.Schema is null ? GetDefaultQueryParameterType() : GetQueryParameterType(x.Schema), Documentation = new() { - Description = x.Description.CleanupDescription(), + DescriptionTemplate = x.Description.CleanupDescription(), }, Kind = x.In switch { @@ -1552,7 +1552,7 @@ private static void AddRequestConfigurationProperties(CodeClass? parameterClass, Kind = CodePropertyKind.QueryParameters, Documentation = new() { - Description = "Request query parameters", + DescriptionTemplate = "Request query parameters", }, Type = new CodeType { TypeDefinition = parameterClass }, }); @@ -1563,7 +1563,7 @@ private static void AddRequestConfigurationProperties(CodeClass? parameterClass, Kind = CodePropertyKind.Headers, Documentation = new() { - Description = "Request headers", + DescriptionTemplate = "Request headers", }, Type = new CodeType { Name = "RequestHeaders", IsExternal = true }, }, @@ -1573,7 +1573,7 @@ private static void AddRequestConfigurationProperties(CodeClass? parameterClass, Kind = CodePropertyKind.Options, Documentation = new() { - Description = "Request options", + DescriptionTemplate = "Request options", }, Type = new CodeType { Name = "IList", IsExternal = true }, }); @@ -1613,7 +1613,7 @@ private void AddRequestBuilderMethodParameters(OpenApiUrlTreeNode currentNode, O Kind = CodeParameterKind.RequestBody, Documentation = new() { - Description = requestBodySchema.Description.CleanupDescription() is string description && !string.IsNullOrEmpty(description) ? + DescriptionTemplate = requestBodySchema.Description.CleanupDescription() is string description && !string.IsNullOrEmpty(description) ? description : "The request body" }, @@ -1630,7 +1630,7 @@ private void AddRequestBuilderMethodParameters(OpenApiUrlTreeNode currentNode, O Kind = CodeParameterKind.RequestBody, Documentation = new() { - Description = "Binary request body", + DescriptionTemplate = "Binary request body", }, Type = new CodeType { @@ -1657,7 +1657,7 @@ private void AddRequestBuilderMethodParameters(OpenApiUrlTreeNode currentNode, O }, Documentation = new() { - Description = "The request body content type." + DescriptionTemplate = "The request body content type." }, PossibleValues = contentTypes.ToList() }); @@ -1670,7 +1670,7 @@ private void AddRequestBuilderMethodParameters(OpenApiUrlTreeNode currentNode, O Kind = CodeParameterKind.RequestConfiguration, Documentation = new() { - Description = "Configuration for the request such as headers, query parameters, and middleware options.", + DescriptionTemplate = "Configuration for the request such as headers, query parameters, and middleware options.", }, }); } @@ -1715,10 +1715,10 @@ private CodeType CreateInheritedModelDeclaration(OpenApiUrlTreeNode currentNode, codeDeclaration = AddModelDeclarationIfDoesntExist(currentNode, currentSchema, className, shortestNamespace, codeDeclaration as CodeClass); } if (codeDeclaration is CodeClass currentClass && - string.IsNullOrEmpty(currentClass.Documentation.Description) && + string.IsNullOrEmpty(currentClass.Documentation.DescriptionTemplate) && string.IsNullOrEmpty(schema.AllOf.LastOrDefault()?.Description) && !string.IsNullOrEmpty(schema.Description)) - currentClass.Documentation.Description = schema.Description.CleanupDescription(); // the last allof entry often is not a reference and doesn't have a description. + currentClass.Documentation.DescriptionTemplate = schema.Description.CleanupDescription(); // the last allof entry often is not a reference and doesn't have a description. return new CodeType { @@ -1918,7 +1918,7 @@ private CodeElement AddModelDeclarationIfDoesntExist(OpenApiUrlTreeNode currentN Flags = enumFlagsExtension?.IsFlags ?? false, Documentation = new() { - Description = !string.IsNullOrEmpty(schemaDescription) || !string.IsNullOrEmpty(schema.Reference?.Id) ? + DescriptionTemplate = !string.IsNullOrEmpty(schemaDescription) || !string.IsNullOrEmpty(schema.Reference?.Id) ? schemaDescription : // if it's a referenced component, we shouldn't use the path item description as it makes it indeterministic currentNode.GetPathItemDescription(Constants.DefaultOpenApiLabel), }, @@ -1949,7 +1949,7 @@ private static void SetEnumOptions(OpenApiSchema schema, CodeEnum target) SerializationName = x, Documentation = new() { - Description = optionDescription?.Description ?? string.Empty, + DescriptionTemplate = optionDescription?.Description ?? string.Empty, }, }; }) @@ -1980,7 +1980,7 @@ private CodeClass AddModelClass(OpenApiUrlTreeNode currentNode, OpenApiSchema sc { DocumentationLabel = schema.ExternalDocs?.Description ?? string.Empty, DocumentationLink = schema.ExternalDocs?.Url, - Description = (string.IsNullOrEmpty(schema.Description) ? schema.AllOf?.FirstOrDefault(static x => !x.IsReferencedSchema() && !string.IsNullOrEmpty(x.Description))?.Description : schema.Description).CleanupDescription(), + DescriptionTemplate = (string.IsNullOrEmpty(schema.Description) ? schema.AllOf?.FirstOrDefault(static x => !x.IsReferencedSchema() && !string.IsNullOrEmpty(x.Description))?.Description : schema.Description).CleanupDescription(), }, Deprecation = schema.GetDeprecationInformation(), }; @@ -2177,7 +2177,7 @@ internal static void AddDiscriminatorMethod(CodeClass newClass, string discrimin Name = refineMethodName("CreateFromDiscriminatorValue"), Documentation = new() { - Description = "Creates a new instance of the appropriate class based on discriminator value", + DescriptionTemplate = "Creates a new instance of the appropriate class based on discriminator value", }, ReturnType = new CodeType { TypeDefinition = newClass, IsNullable = false }, Kind = CodeMethodKind.Factory, @@ -2193,7 +2193,7 @@ internal static void AddDiscriminatorMethod(CodeClass newClass, string discrimin Kind = CodeParameterKind.ParseNode, Documentation = new() { - Description = "The parse node to use to read the discriminator value and create the object", + DescriptionTemplate = "The parse node to use to read the discriminator value and create the object", }, Optional = false, Type = new CodeType { Name = ParseNodeInterface, IsExternal = true }, @@ -2276,7 +2276,7 @@ internal static void AddSerializationMembers(CodeClass model, bool includeAdditi Access = AccessModifier.Public, Documentation = new() { - Description = "The deserialization information for the current model", + DescriptionTemplate = "The deserialization information for the current model", }, IsAsync = false, ReturnType = new CodeType @@ -2298,7 +2298,7 @@ internal static void AddSerializationMembers(CodeClass model, bool includeAdditi IsAsync = false, Documentation = new() { - Description = "Serializes information the current object", + DescriptionTemplate = "Serializes information the current object", }, ReturnType = new CodeType { Name = VoidType, IsNullable = false, IsExternal = true }, Parent = model, @@ -2308,7 +2308,7 @@ internal static void AddSerializationMembers(CodeClass model, bool includeAdditi Name = "writer", Documentation = new() { - Description = "Serialization writer to use to serialize this model", + DescriptionTemplate = "Serialization writer to use to serialize this model", }, Kind = CodeParameterKind.Serializer, Type = new CodeType { Name = "ISerializationWriter", IsExternal = true, IsNullable = false }, @@ -2330,7 +2330,7 @@ internal static void AddSerializationMembers(CodeClass model, bool includeAdditi Kind = CodePropertyKind.AdditionalData, Documentation = new() { - Description = "Stores additional data not described in the OpenAPI description found when deserializing. Can be used for serialization as well.", + DescriptionTemplate = "Stores additional data not described in the OpenAPI description found when deserializing. Can be used for serialization as well.", }, Type = new CodeType { @@ -2358,7 +2358,7 @@ internal static void AddSerializationMembers(CodeClass model, bool includeAdditi Kind = CodePropertyKind.BackingStore, Documentation = new() { - Description = "Stores model information.", + DescriptionTemplate = "Stores model information.", }, ReadOnly = true, Type = new CodeType @@ -2387,7 +2387,7 @@ internal static void AddSerializationMembers(CodeClass model, bool includeAdditi Kind = CodeClassKind.QueryParameters, Documentation = new() { - Description = (operation.Description is string description && !string.IsNullOrEmpty(description) ? + DescriptionTemplate = (operation.Description is string description && !string.IsNullOrEmpty(description) ? description : operation.Summary).CleanupDescription(), }, @@ -2438,7 +2438,7 @@ private void AddPropertyForQueryParameter(OpenApiUrlTreeNode node, OperationType Name = parameter.Name.SanitizeParameterNameForCodeSymbols(), Documentation = new() { - Description = parameter.Description.CleanupDescription(), + DescriptionTemplate = parameter.Description.CleanupDescription(), }, Kind = CodePropertyKind.QueryParameter, Type = resultType, diff --git a/src/Kiota.Builder/Refiners/CommonLanguageRefiner.cs b/src/Kiota.Builder/Refiners/CommonLanguageRefiner.cs index 8220666d32..bb168bb369 100644 --- a/src/Kiota.Builder/Refiners/CommonLanguageRefiner.cs +++ b/src/Kiota.Builder/Refiners/CommonLanguageRefiner.cs @@ -188,7 +188,7 @@ current.Parent is CodeClass parentClass && ReturnType = (CodeTypeBase)currentProperty.Type.Clone(), Documentation = new() { - Description = $"Gets the {currentProperty.WireName} property value. {currentProperty.Documentation.Description}", + DescriptionTemplate = $"Gets the {currentProperty.WireName} property value. {currentProperty.Documentation.DescriptionTemplate}", }, AccessedProperty = currentProperty, Deprecation = currentProperty.Deprecation, @@ -203,7 +203,7 @@ current.Parent is CodeClass parentClass && Kind = CodeMethodKind.Setter, Documentation = new() { - Description = $"Sets the {currentProperty.WireName} property value. {currentProperty.Documentation.Description}", + DescriptionTemplate = $"Sets the {currentProperty.WireName} property value. {currentProperty.Documentation.DescriptionTemplate}", }, AccessedProperty = currentProperty, ReturnType = new CodeType @@ -223,7 +223,7 @@ current.Parent is CodeClass parentClass && Kind = CodeParameterKind.SetterValue, Documentation = new() { - Description = $"Value to set for the {currentProperty.WireName} property.", + DescriptionTemplate = $"Value to set for the {currentProperty.WireName} property.", }, Optional = parameterAsOptional, Type = (CodeTypeBase)currentProperty.Type.Clone(), @@ -251,7 +251,7 @@ protected static void AddConstructorsForDefaultValues(CodeElement current, bool IsAsync = false, Documentation = new() { - Description = $"Instantiates a new {current.Name} and sets the default values.", + DescriptionTemplate = $"Instantiates a new {current.Name} and sets the default values.", }, }); CrawlTree(current, x => AddConstructorsForDefaultValues(x, addIfInherited, forceAdd, classKindsToExclude)); @@ -483,7 +483,7 @@ private static CodeType ConvertComposedTypeToWrapper(CodeClass codeClass, CodeCo Name = codeComposedType.Name, Documentation = new() { - Description = description, + DescriptionTemplate = description, }, Deprecation = codeComposedType.Deprecation, }).Last(); @@ -495,7 +495,7 @@ private static CodeType ConvertComposedTypeToWrapper(CodeClass codeClass, CodeCo Name = codeComposedType.Name, Documentation = new() { - Description = description + DescriptionTemplate = description }, }) .First(); @@ -515,7 +515,7 @@ private static CodeType ConvertComposedTypeToWrapper(CodeClass codeClass, CodeCo Name = codeComposedType.Name, Documentation = new() { - Description = description + DescriptionTemplate = description }, }) .First(); @@ -528,7 +528,7 @@ private static CodeType ConvertComposedTypeToWrapper(CodeClass codeClass, CodeCo Type = x, Documentation = new() { - Description = $"Composed type representation for type {x.Name}" + DescriptionTemplate = $"Composed type representation for type {x.Name}" }, }).ToArray()); if (codeComposedType.Types.All(static x => x.TypeDefinition is CodeClass targetClass && targetClass.IsOfKind(CodeClassKind.Model) || @@ -570,7 +570,7 @@ private static CodeType ConvertComposedTypeToWrapper(CodeClass codeClass, CodeCo IsStatic = false, Documentation = new() { - Description = "Determines if the current object is a wrapper around a composed type", + DescriptionTemplate = "Determines if the current object is a wrapper around a composed type", }, }); } @@ -1324,7 +1324,7 @@ public void AddQueryParameterMapperMethod(CodeElement currentElement, string met Kind = CodeMethodKind.QueryParametersMapper, Documentation = new() { - Description = "Maps the query parameters names to their encoded names for the URI template parsing.", + DescriptionTemplate = "Maps the query parameters names to their encoded names for the URI template parsing.", }, }).First(); method.AddParameter(new CodeParameter @@ -1339,7 +1339,7 @@ public void AddQueryParameterMapperMethod(CodeElement currentElement, string met Optional = false, Documentation = new() { - Description = "The original query parameter name in the class.", + DescriptionTemplate = "The original query parameter name in the class.", }, }); } @@ -1491,7 +1491,7 @@ internal static void AddPrimaryErrorMessage(CodeElement currentElement, string n Type = type(), Documentation = new() { - Description = "The primary error message.", + DescriptionTemplate = "The primary error message.", }, }); } @@ -1507,7 +1507,7 @@ internal static void AddPrimaryErrorMessage(CodeElement currentElement, string n IsStatic = false, Documentation = new() { - Description = "The primary error message.", + DescriptionTemplate = "The primary error message.", }, }); } diff --git a/src/Kiota.Builder/Refiners/GoRefiner.cs b/src/Kiota.Builder/Refiners/GoRefiner.cs index c6b2a501f6..0878379326 100644 --- a/src/Kiota.Builder/Refiners/GoRefiner.cs +++ b/src/Kiota.Builder/Refiners/GoRefiner.cs @@ -444,7 +444,7 @@ protected static void RenameCancellationParameter(CodeElement currentElement) if (currentElement is CodeMethod currentMethod && currentMethod.IsOfKind(CodeMethodKind.RequestExecutor) && currentMethod.Parameters.OfKind(CodeParameterKind.Cancellation) is CodeParameter parameter) { parameter.Name = ContextParameterName; - parameter.Documentation.Description = ContextVarDescription; + parameter.Documentation.DescriptionTemplate = ContextVarDescription; parameter.Kind = CodeParameterKind.Cancellation; parameter.Optional = false; parameter.Type.Name = conventions.ContextVarTypeName; @@ -469,7 +469,7 @@ private static void AddContextParameterToGeneratorMethods(CodeElement currentEle Kind = CodeParameterKind.Cancellation, Optional = false, Documentation = { - Description = ContextVarDescription, + DescriptionTemplate = ContextVarDescription, }, }); CrawlTree(currentElement, AddContextParameterToGeneratorMethods); diff --git a/src/Kiota.Builder/Refiners/JavaRefiner.cs b/src/Kiota.Builder/Refiners/JavaRefiner.cs index 33fe45e1d5..c6145fa812 100644 --- a/src/Kiota.Builder/Refiners/JavaRefiner.cs +++ b/src/Kiota.Builder/Refiners/JavaRefiner.cs @@ -188,7 +188,7 @@ currentMethod.Parent is CodeClass parentClass && Optional = false, Documentation = new() { - Description = "Discriminator value from the payload", + DescriptionTemplate = "Discriminator value from the payload", }, Name = "discriminatorValue" }); @@ -539,7 +539,7 @@ private void AddQueryParameterExtractorMethod(CodeElement currentElement, string Kind = CodeMethodKind.QueryParametersMapper, Documentation = new() { - Description = "Extracts the query parameters into a map for the URI template parsing.", + DescriptionTemplate = "Extracts the query parameters into a map for the URI template parsing.", }, }); } diff --git a/src/Kiota.Builder/Refiners/PhpRefiner.cs b/src/Kiota.Builder/Refiners/PhpRefiner.cs index 93df413e31..9a2df93aac 100644 --- a/src/Kiota.Builder/Refiners/PhpRefiner.cs +++ b/src/Kiota.Builder/Refiners/PhpRefiner.cs @@ -266,7 +266,7 @@ private static void CorrectParameterType(CodeElement codeElement) if (x.IsOfKind(CodeParameterKind.ParseNode)) x.Type.Name = "ParseNode"; else - x.Documentation.Description += " or a String representing the raw URL."; + x.Documentation.DescriptionTemplate += " or a String representing the raw URL."; }); currentMethod.Parameters.Where(x => x.IsOfKind(CodeParameterKind.BackingStore) && currentMethod.IsOfKind(CodeMethodKind.ClientConstructor)).ToList().ForEach(static x => @@ -356,7 +356,7 @@ private static void AddRequestConfigurationConstructors(CodeElement codeElement) IsAsync = false, Documentation = new() { - Description = $"Instantiates a new {codeClass.Name} and sets the default values.", + DescriptionTemplate = $"Instantiates a new {codeClass.Name} and sets the default values.", }, ReturnType = new CodeType { Name = "void" }, }; @@ -417,7 +417,7 @@ private static void AddQueryParameterFactoryMethod(CodeElement codeElement) Kind = CodeMethodKind.Factory, Documentation = new CodeDocumentation { - Description = $"Instantiates a new {queryParameterProperty.Type.Name}." + DescriptionTemplate = $"Instantiates a new {queryParameterProperty.Type.Name}." }, ReturnType = new CodeType { Name = queryParameterProperty.Type.Name, TypeDefinition = queryParameterProperty.Type, IsNullable = false } }; diff --git a/src/Kiota.Builder/Refiners/PythonRefiner.cs b/src/Kiota.Builder/Refiners/PythonRefiner.cs index 3f1885a4bb..2640af6acb 100644 --- a/src/Kiota.Builder/Refiners/PythonRefiner.cs +++ b/src/Kiota.Builder/Refiners/PythonRefiner.cs @@ -294,7 +294,7 @@ private static void CorrectMethodType(CodeMethod currentMethod) urlTplParams.Type is CodeType originalType) { originalType.Name = "Union[str, Dict[str, Any]]"; - urlTplParams.Documentation.Description = "The raw url or the url-template parameters for the request."; + urlTplParams.Documentation.DescriptionTemplate = "The raw url or the url-template parameters for the request."; } } CorrectCoreTypes(currentMethod.Parent as CodeClass, DateTypesReplacements, currentMethod.Parameters diff --git a/src/Kiota.Builder/Refiners/SwiftRefiner.cs b/src/Kiota.Builder/Refiners/SwiftRefiner.cs index 1a2cc104c5..0d1d59ca6f 100644 --- a/src/Kiota.Builder/Refiners/SwiftRefiner.cs +++ b/src/Kiota.Builder/Refiners/SwiftRefiner.cs @@ -204,7 +204,7 @@ private void AddRootClassForExtensions(CodeElement current) Kind = CodeClassKind.BarrelInitializer, Documentation = new() { - Description = "Root class for extensions", + DescriptionTemplate = "Root class for extensions", }, }); } diff --git a/src/Kiota.Builder/Refiners/TypeScriptRefiner.cs b/src/Kiota.Builder/Refiners/TypeScriptRefiner.cs index 43fdb97c1a..6d921a56f1 100644 --- a/src/Kiota.Builder/Refiners/TypeScriptRefiner.cs +++ b/src/Kiota.Builder/Refiners/TypeScriptRefiner.cs @@ -580,7 +580,7 @@ private static void CorrectMethodType(CodeMethod currentMethod) if (currentMethod.Parameters.FirstOrDefault(x => x.IsOfKind(CodeParameterKind.PathParameters)) is CodeParameter urlTplParams && urlTplParams.Type is CodeType originalType) { originalType.Name = "Record"; - urlTplParams.Documentation.Description = "The raw url or the Url template parameters for the request."; + urlTplParams.Documentation.DescriptionTemplate = "The raw url or the Url template parameters for the request."; var unionType = new CodeUnionType { Name = "rawUrlOrTemplateParameters", diff --git a/src/Kiota.Builder/Writers/CLI/CliCodeMethodWriter.cs b/src/Kiota.Builder/Writers/CLI/CliCodeMethodWriter.cs index dc9c76c3fc..2f68db8c62 100644 --- a/src/Kiota.Builder/Writers/CLI/CliCodeMethodWriter.cs +++ b/src/Kiota.Builder/Writers/CLI/CliCodeMethodWriter.cs @@ -476,7 +476,7 @@ private static void WriteCommandDescription(CodeMethod codeElement, LanguageWrit var builder = new StringBuilder(); if (documentation.DescriptionAvailable) { - builder.Append(documentation.Description); + builder.Append(documentation.DescriptionTemplate); } // Add content type values to description. diff --git a/src/Kiota.Builder/Writers/CSharp/CSharpConventionService.cs b/src/Kiota.Builder/Writers/CSharp/CSharpConventionService.cs index f7197d2894..7db7e4fba0 100644 --- a/src/Kiota.Builder/Writers/CSharp/CSharpConventionService.cs +++ b/src/Kiota.Builder/Writers/CSharp/CSharpConventionService.cs @@ -50,7 +50,7 @@ public void WriteLongDescription(CodeDocumentation documentation, LanguageWriter { writer.WriteLine($"{DocCommentPrefix}"); if (documentation.DescriptionAvailable) - writer.WriteLine($"{DocCommentPrefix}{documentation.Description.CleanupXMLString()}"); + writer.WriteLine($"{DocCommentPrefix}{documentation.DescriptionTemplate.CleanupXMLString()}"); if (documentation.ExternalDocumentationAvailable) writer.WriteLine($"{DocCommentPrefix}{documentation.DocumentationLabel} "); writer.WriteLine($"{DocCommentPrefix}"); diff --git a/src/Kiota.Builder/Writers/CSharp/CodeEnumWriter.cs b/src/Kiota.Builder/Writers/CSharp/CodeEnumWriter.cs index 9d5cff7f51..7845a9b2d4 100644 --- a/src/Kiota.Builder/Writers/CSharp/CodeEnumWriter.cs +++ b/src/Kiota.Builder/Writers/CSharp/CodeEnumWriter.cs @@ -29,7 +29,7 @@ public override void WriteCodeElement(CodeEnum codeElement, LanguageWriter write writer.WriteLine(x); writer.StartBlock($"namespace {codeNamespace.Name} {{"); } - conventions.WriteShortDescription(codeElement.Documentation.Description, writer); + conventions.WriteShortDescription(codeElement.Documentation.DescriptionTemplate, writer); if (codeElement.Flags) writer.WriteLine("[Flags]"); conventions.WriteDeprecationAttribute(codeElement, writer); @@ -37,7 +37,7 @@ public override void WriteCodeElement(CodeEnum codeElement, LanguageWriter write var idx = 0; foreach (var option in codeElement.Options) { - conventions.WriteShortDescription(option.Documentation.Description, writer); + conventions.WriteShortDescription(option.Documentation.DescriptionTemplate, writer); if (option.IsNameEscaped) { diff --git a/src/Kiota.Builder/Writers/CSharp/CodeIndexerWriter.cs b/src/Kiota.Builder/Writers/CSharp/CodeIndexerWriter.cs index 1fb64158b2..a7a75bbc74 100644 --- a/src/Kiota.Builder/Writers/CSharp/CodeIndexerWriter.cs +++ b/src/Kiota.Builder/Writers/CSharp/CodeIndexerWriter.cs @@ -12,8 +12,8 @@ public override void WriteCodeElement(CodeIndexer codeElement, LanguageWriter wr ArgumentNullException.ThrowIfNull(writer); if (codeElement.Parent is not CodeClass parentClass) throw new InvalidOperationException("The parent of a property should be a class"); var returnType = conventions.GetTypeString(codeElement.ReturnType, codeElement); - conventions.WriteShortDescription(codeElement.Documentation.Description, writer); - writer.WriteLine($"{conventions.DocCommentPrefix}{codeElement.IndexParameter.Documentation.Description.CleanupXMLString()}"); + conventions.WriteShortDescription(codeElement.Documentation.DescriptionTemplate, writer); + writer.WriteLine($"{conventions.DocCommentPrefix}{codeElement.IndexParameter.Documentation.DescriptionTemplate.CleanupXMLString()}"); conventions.WriteDeprecationAttribute(codeElement, writer); writer.StartBlock($"public {returnType} this[{conventions.GetTypeString(codeElement.IndexParameter.Type, codeElement)} position] {{ get {{"); if (parentClass.GetPropertyOfKind(CodePropertyKind.PathParameters) is CodeProperty pathParametersProp) diff --git a/src/Kiota.Builder/Writers/CSharp/CodeMethodWriter.cs b/src/Kiota.Builder/Writers/CSharp/CodeMethodWriter.cs index 8ecebe7690..65c206678f 100644 --- a/src/Kiota.Builder/Writers/CSharp/CodeMethodWriter.cs +++ b/src/Kiota.Builder/Writers/CSharp/CodeMethodWriter.cs @@ -545,7 +545,7 @@ private void WriteMethodDocumentation(CodeMethod code, LanguageWriter writer) foreach (var paramWithDescription in code.Parameters .Where(static x => x.Documentation.DescriptionAvailable) .OrderBy(static x => x.Name, StringComparer.OrdinalIgnoreCase)) - writer.WriteLine($"{conventions.DocCommentPrefix}{paramWithDescription.Documentation.Description.CleanupXMLString()}"); + writer.WriteLine($"{conventions.DocCommentPrefix}{paramWithDescription.Documentation.DescriptionTemplate.CleanupXMLString()}"); conventions.WriteDeprecationAttribute(code, writer); } private static readonly BaseCodeParameterOrderComparer parameterOrderComparer = new(); diff --git a/src/Kiota.Builder/Writers/CSharp/CodePropertyWriter.cs b/src/Kiota.Builder/Writers/CSharp/CodePropertyWriter.cs index 48fef8fa98..b2f3aa476f 100644 --- a/src/Kiota.Builder/Writers/CSharp/CodePropertyWriter.cs +++ b/src/Kiota.Builder/Writers/CSharp/CodePropertyWriter.cs @@ -16,7 +16,7 @@ public override void WriteCodeElement(CodeProperty codeElement, LanguageWriter w && codeElement.IsOfKind( CodePropertyKind.Custom, CodePropertyKind.QueryParameter);// Other property types are appropriately constructor initialized - conventions.WriteShortDescription(codeElement.Documentation.Description, writer); + conventions.WriteShortDescription(codeElement.Documentation.DescriptionTemplate, writer); conventions.WriteDeprecationAttribute(codeElement, writer); if (isNullableReferenceType) { diff --git a/src/Kiota.Builder/Writers/Go/CodeClassDeclarationWriter.cs b/src/Kiota.Builder/Writers/Go/CodeClassDeclarationWriter.cs index 79920c97cb..e609e7c11b 100644 --- a/src/Kiota.Builder/Writers/Go/CodeClassDeclarationWriter.cs +++ b/src/Kiota.Builder/Writers/Go/CodeClassDeclarationWriter.cs @@ -15,7 +15,7 @@ protected override void WriteTypeDeclaration(ClassDeclaration codeElement, Langu ArgumentNullException.ThrowIfNull(writer); var className = codeElement.Name.ToFirstCharacterUpperCase(); if (codeElement.Parent is not CodeClass currentClass) throw new InvalidOperationException("The parent of a class declaration should be a class"); - conventions.WriteShortDescription($"{className} {currentClass.Documentation.Description.ToFirstCharacterLowerCase()}", writer); + conventions.WriteShortDescription($"{className} {currentClass.Documentation.DescriptionTemplate.ToFirstCharacterLowerCase()}", writer); conventions.WriteDeprecation(currentClass, writer); conventions.WriteLinkDescription(currentClass.Documentation, writer); writer.StartBlock($"type {className} struct {{"); diff --git a/src/Kiota.Builder/Writers/Go/CodeEnumWriter.cs b/src/Kiota.Builder/Writers/Go/CodeEnumWriter.cs index 610d736db6..903c4425cd 100644 --- a/src/Kiota.Builder/Writers/Go/CodeEnumWriter.cs +++ b/src/Kiota.Builder/Writers/Go/CodeEnumWriter.cs @@ -22,7 +22,7 @@ public override void WriteCodeElement(CodeEnum codeElement, LanguageWriter write writer.CloseBlock(")"); var typeName = codeElement.Name.ToFirstCharacterUpperCase(); - conventions.WriteShortDescription(codeElement.Documentation.Description, writer); + conventions.WriteShortDescription(codeElement.Documentation.DescriptionTemplate, writer); conventions.WriteDeprecation(codeElement, writer); writer.WriteLines($"type {typeName} int", string.Empty, @@ -34,8 +34,8 @@ public override void WriteCodeElement(CodeEnum codeElement, LanguageWriter write int power = 0; foreach (var item in enumOptions) { - if (!string.IsNullOrEmpty(item.Documentation.Description)) - writer.WriteLine($"// {item.Documentation.Description}"); + if (!string.IsNullOrEmpty(item.Documentation.DescriptionTemplate)) + writer.WriteLine($"// {item.Documentation.DescriptionTemplate}"); if (isMultiValue) writer.WriteLine($"{item.Name.ToUpperInvariant()}_{typeName.ToUpperInvariant()} = {(int)Math.Pow(2, power)}"); diff --git a/src/Kiota.Builder/Writers/Go/CodeInterfaceDeclarationWriter.cs b/src/Kiota.Builder/Writers/Go/CodeInterfaceDeclarationWriter.cs index d6a31487db..80e00c54c5 100644 --- a/src/Kiota.Builder/Writers/Go/CodeInterfaceDeclarationWriter.cs +++ b/src/Kiota.Builder/Writers/Go/CodeInterfaceDeclarationWriter.cs @@ -13,7 +13,7 @@ protected override void WriteTypeDeclaration(InterfaceDeclaration codeElement, L ArgumentNullException.ThrowIfNull(writer); if (codeElement.Parent is not CodeInterface inter) throw new InvalidOperationException("Expected the parent to be an interface"); var interName = codeElement.Name.ToFirstCharacterUpperCase(); - conventions.WriteShortDescription($"{interName} {inter.Documentation.Description.ToFirstCharacterLowerCase()}", writer); + conventions.WriteShortDescription($"{interName} {inter.Documentation.DescriptionTemplate.ToFirstCharacterLowerCase()}", writer); if (codeElement.Parent is CodeInterface currentInterface && currentInterface.OriginalClass is not null) conventions.WriteDeprecation(currentInterface.OriginalClass, writer); conventions.WriteLinkDescription(inter.Documentation, writer); diff --git a/src/Kiota.Builder/Writers/Go/CodeMethodWriter.cs b/src/Kiota.Builder/Writers/Go/CodeMethodWriter.cs index 9274be5c87..e6398723a4 100644 --- a/src/Kiota.Builder/Writers/Go/CodeMethodWriter.cs +++ b/src/Kiota.Builder/Writers/Go/CodeMethodWriter.cs @@ -291,7 +291,7 @@ private void WriteFactoryMethodBodyForUnionModelForUnDiscriminatedTypes(CodeClas private void WriteMethodDocumentation(CodeMethod code, string methodName, LanguageWriter writer) { if (code.Documentation.DescriptionAvailable) - conventions.WriteShortDescription($"{methodName.ToFirstCharacterUpperCase()} {code.Documentation.Description.ToFirstCharacterLowerCase()}", writer); + conventions.WriteShortDescription($"{methodName.ToFirstCharacterUpperCase()} {code.Documentation.DescriptionTemplate.ToFirstCharacterLowerCase()}", writer); conventions.WriteDeprecation(code, writer); conventions.WriteLinkDescription(code.Documentation, writer); } diff --git a/src/Kiota.Builder/Writers/Go/CodePropertyWriter.cs b/src/Kiota.Builder/Writers/Go/CodePropertyWriter.cs index a139c2447e..3003f1d81b 100644 --- a/src/Kiota.Builder/Writers/Go/CodePropertyWriter.cs +++ b/src/Kiota.Builder/Writers/Go/CodePropertyWriter.cs @@ -26,7 +26,7 @@ public override void WriteCodeElement(CodeProperty codeElement, LanguageWriter w goto default; default: var returnType = codeElement.Parent is CodeElement parent ? conventions.GetTypeString(codeElement.Type, parent) : string.Empty; - conventions.WriteShortDescription(codeElement.Documentation.Description, writer); + conventions.WriteShortDescription(codeElement.Documentation.DescriptionTemplate, writer); conventions.WriteDeprecation(codeElement, writer); writer.WriteLine($"{propertyName} {returnType}{suffix}"); break; diff --git a/src/Kiota.Builder/Writers/Java/CodeEnumWriter.cs b/src/Kiota.Builder/Writers/Java/CodeEnumWriter.cs index f643363124..06ac05e55b 100644 --- a/src/Kiota.Builder/Writers/Java/CodeEnumWriter.cs +++ b/src/Kiota.Builder/Writers/Java/CodeEnumWriter.cs @@ -27,7 +27,7 @@ public override void WriteCodeElement(CodeEnum codeElement, LanguageWriter write var lastEnumOption = enumOptions.Last(); foreach (var enumOption in enumOptions) { - conventions.WriteShortDescription(enumOption.Documentation.Description, writer); + conventions.WriteShortDescription(enumOption.Documentation.DescriptionTemplate, writer); writer.WriteLine($"{enumOption.Name}(\"{enumOption.SerializationName}\"){(enumOption == lastEnumOption ? ";" : ",")}"); } writer.WriteLines("public final String value;", diff --git a/src/Kiota.Builder/Writers/Java/CodeMethodWriter.cs b/src/Kiota.Builder/Writers/Java/CodeMethodWriter.cs index 55c24cb677..c50c36e587 100644 --- a/src/Kiota.Builder/Writers/Java/CodeMethodWriter.cs +++ b/src/Kiota.Builder/Writers/Java/CodeMethodWriter.cs @@ -742,7 +742,7 @@ private void WriteMethodDocumentation(CodeMethod code, LanguageWriter writer, st code.Parameters .Where(static x => x.Documentation.DescriptionAvailable) .OrderBy(static x => x.Name, StringComparer.OrdinalIgnoreCase) - .Select(x => $"@param {x.Name} {JavaConventionService.RemoveInvalidDescriptionCharacters(x.Documentation.Description)}") + .Select(x => $"@param {x.Name} {JavaConventionService.RemoveInvalidDescriptionCharacters(x.Documentation.DescriptionTemplate)}") .Union(new[] { returnRemark })); if (!returnVoid) //Nullable/Nonnull annotations for returns are a part of Method Documentation writer.WriteLine(code.ReturnType.IsNullable ? "@jakarta.annotation.Nullable" : "@jakarta.annotation.Nonnull"); diff --git a/src/Kiota.Builder/Writers/Java/JavaConventionService.cs b/src/Kiota.Builder/Writers/Java/JavaConventionService.cs index 7d7d749cad..fd0f8367b6 100644 --- a/src/Kiota.Builder/Writers/Java/JavaConventionService.cs +++ b/src/Kiota.Builder/Writers/Java/JavaConventionService.cs @@ -110,7 +110,7 @@ public void WriteLongDescription(CodeElement element, LanguageWriter writer, IEn { writer.WriteLine(DocCommentStart); if (documentation.DescriptionAvailable) - writer.WriteLine($"{DocCommentPrefix}{RemoveInvalidDescriptionCharacters(documentation.Description)}"); + writer.WriteLine($"{DocCommentPrefix}{RemoveInvalidDescriptionCharacters(documentation.DescriptionTemplate)}"); foreach (var additionalRemark in remarks.Where(static x => !string.IsNullOrEmpty(x))) writer.WriteLine($"{DocCommentPrefix}{additionalRemark}"); if (element is IDeprecableElement deprecableElement && deprecableElement.Deprecation is not null && deprecableElement.Deprecation.IsDeprecated) diff --git a/src/Kiota.Builder/Writers/Php/CodeMethodWriter.cs b/src/Kiota.Builder/Writers/Php/CodeMethodWriter.cs index 8172fcbcbe..075929d5d7 100644 --- a/src/Kiota.Builder/Writers/Php/CodeMethodWriter.cs +++ b/src/Kiota.Builder/Writers/Php/CodeMethodWriter.cs @@ -258,7 +258,7 @@ private static void AssignPropertyFromParameter(CodeClass parentClass, CodeMetho private void WriteMethodPhpDocs(CodeMethod codeMethod, LanguageWriter writer) { - var methodDescription = codeMethod.Documentation.Description; + var methodDescription = codeMethod.Documentation.DescriptionTemplate; var methodThrows = codeMethod.IsOfKind(CodeMethodKind.RequestExecutor); var hasMethodDescription = !string.IsNullOrEmpty(methodDescription.Trim()); if (!hasMethodDescription && !codeMethod.Parameters.Any()) @@ -306,9 +306,9 @@ private string GetParameterDocString(CodeMethod codeMethod, CodeParameter x) if (codeMethod.IsOfKind(CodeMethodKind.Setter) && (codeMethod.AccessedProperty?.IsOfKind(CodePropertyKind.AdditionalData) ?? false)) { - return $"@param array $value {x?.Documentation.Description}"; + return $"@param array $value {x?.Documentation.DescriptionTemplate}"; } - return $"@param {conventions.GetParameterDocNullable(x, x)} {x?.Documentation.Description}"; + return $"@param {conventions.GetParameterDocNullable(x, x)} {x?.Documentation.DescriptionTemplate}"; } private static readonly BaseCodeParameterOrderComparer parameterOrderComparer = new(); diff --git a/src/Kiota.Builder/Writers/Php/CodePropertyWriter.cs b/src/Kiota.Builder/Writers/Php/CodePropertyWriter.cs index bc68cd145e..e29df89762 100644 --- a/src/Kiota.Builder/Writers/Php/CodePropertyWriter.cs +++ b/src/Kiota.Builder/Writers/Php/CodePropertyWriter.cs @@ -32,7 +32,7 @@ public override void WriteCodeElement(CodeProperty codeElement, LanguageWriter w private void WritePropertyDocComment(CodeProperty codeProperty, LanguageWriter writer) { - var propertyDescription = codeProperty.Documentation.Description; + var propertyDescription = codeProperty.Documentation.DescriptionTemplate; var hasDescription = codeProperty.Documentation.DescriptionAvailable; var collectionKind = codeProperty.Type.IsArray || codeProperty.Type.IsCollection; @@ -63,7 +63,7 @@ private string GetCollectionDocString(CodeProperty codeProperty) private void WriteRequestBuilderBody(CodeProperty codeElement, LanguageWriter writer, string returnType, string propertyAccess, string propertyName) { - conventions.WriteShortDescription(codeElement.Documentation.Description, writer); + conventions.WriteShortDescription(codeElement.Documentation.DescriptionTemplate, writer); writer.WriteLine($"{propertyAccess} function {propertyName}(): {returnType} {{"); writer.IncreaseIndent(); conventions.AddRequestBuilderBody(returnType, writer); diff --git a/src/Kiota.Builder/Writers/Php/PhpConventionService.cs b/src/Kiota.Builder/Writers/Php/PhpConventionService.cs index cf02f48669..b29e086c6b 100644 --- a/src/Kiota.Builder/Writers/Php/PhpConventionService.cs +++ b/src/Kiota.Builder/Writers/Php/PhpConventionService.cs @@ -160,7 +160,7 @@ public void WriteLongDescription(CodeDocumentation codeDocumentation, LanguageWr { writer.WriteLine(DocCommentStart); if (codeDocumentation.DescriptionAvailable) - writer.WriteLine($"{DocCommentPrefix}{RemoveInvalidDescriptionCharacters(codeDocumentation.Description)}"); + writer.WriteLine($"{DocCommentPrefix}{RemoveInvalidDescriptionCharacters(codeDocumentation.DescriptionTemplate)}"); foreach (var additionalRemark in enumerableArray.Where(static x => !string.IsNullOrEmpty(x))) writer.WriteLine($"{DocCommentPrefix}{additionalRemark}"); diff --git a/src/Kiota.Builder/Writers/Python/CodeEnumWriter.cs b/src/Kiota.Builder/Writers/Python/CodeEnumWriter.cs index 89eea849dd..2464a22049 100644 --- a/src/Kiota.Builder/Writers/Python/CodeEnumWriter.cs +++ b/src/Kiota.Builder/Writers/Python/CodeEnumWriter.cs @@ -24,7 +24,7 @@ public override void WriteCodeElement(CodeEnum codeElement, LanguageWriter write { codeElement.Options.ToList().ForEach(x => { - conventions.WriteInLineDescription(x.Documentation.Description, writer); + conventions.WriteInLineDescription(x.Documentation.DescriptionTemplate, writer); writer.WriteLine($"{x.Name} = \"{x.WireName}\","); }); } diff --git a/src/Kiota.Builder/Writers/Python/CodeMethodWriter.cs b/src/Kiota.Builder/Writers/Python/CodeMethodWriter.cs index 39af4fe555..b57236d080 100644 --- a/src/Kiota.Builder/Writers/Python/CodeMethodWriter.cs +++ b/src/Kiota.Builder/Writers/Python/CodeMethodWriter.cs @@ -387,7 +387,7 @@ private void WriteDirectAccessProperties(CodeClass parentClass, LanguageWriter w _codeUsingWriter.WriteDeferredImport(parentClass, enumDefinition.Name, writer); defaultValue = $"{enumDefinition.Name}({defaultValue})"; } - conventions.WriteInLineDescription(propWithDefault.Documentation.Description, writer); + conventions.WriteInLineDescription(propWithDefault.Documentation.DescriptionTemplate, writer); if (parentClass.IsOfKind(CodeClassKind.Model)) { writer.WriteLine($"{propWithDefault.Name}: {(propWithDefault.Type.IsNullable ? "Optional[" : string.Empty)}{returnType}{(propWithDefault.Type.IsNullable ? "]" : string.Empty)} = {defaultValue}"); @@ -416,7 +416,7 @@ private void WriteSetterAccessProperties(CodeClass parentClass, LanguageWriter w defaultValue = $"{enumDefinition.Name}({defaultValue})"; } var returnType = conventions.GetTypeString(propWithDefault.Type, propWithDefault, true, writer); - conventions.WriteInLineDescription(propWithDefault.Documentation.Description, writer); + conventions.WriteInLineDescription(propWithDefault.Documentation.DescriptionTemplate, writer); var setterString = $"{propWithDefault.Name}: {(propWithDefault.Type.IsNullable ? "Optional[" : string.Empty)}{returnType}{(propWithDefault.Type.IsNullable ? "]" : string.Empty)} = {defaultValue}"; if (parentClass.IsOfKind(CodeClassKind.Model)) { @@ -434,7 +434,7 @@ private void WriteSetterAccessPropertiesWithoutDefaults(CodeClass parentClass, L .ThenBy(static x => x.Name)) { var returnType = conventions.GetTypeString(propWithoutDefault.Type, propWithoutDefault, true, writer); - conventions.WriteInLineDescription(propWithoutDefault.Documentation.Description, writer); + conventions.WriteInLineDescription(propWithoutDefault.Documentation.DescriptionTemplate, writer); if (parentClass.IsOfKind(CodeClassKind.Model)) writer.WriteLine($"{propWithoutDefault.Name}: {(propWithoutDefault.Type.IsNullable ? "Optional[" : string.Empty)}{returnType}{(propWithoutDefault.Type.IsNullable ? "]" : string.Empty)} = None"); else @@ -711,7 +711,7 @@ private void WriteMethodDocumentation(CodeMethod code, LanguageWriter writer, st code.Parameters .Where(static x => x.Documentation.DescriptionAvailable) .OrderBy(static x => x.Name, StringComparer.OrdinalIgnoreCase) - .Select(x => $"param {x.Name}: {PythonConventionService.RemoveInvalidDescriptionCharacters(x.Documentation.Description)}") + .Select(x => $"param {x.Name}: {PythonConventionService.RemoveInvalidDescriptionCharacters(x.Documentation.DescriptionTemplate)}") .Union(new[] { returnRemark })); conventions.WriteDeprecationWarning(code, writer); } diff --git a/src/Kiota.Builder/Writers/Python/CodePropertyWriter.cs b/src/Kiota.Builder/Writers/Python/CodePropertyWriter.cs index 0605377453..ca963d884f 100644 --- a/src/Kiota.Builder/Writers/Python/CodePropertyWriter.cs +++ b/src/Kiota.Builder/Writers/Python/CodePropertyWriter.cs @@ -38,7 +38,7 @@ public override void WriteCodeElement(CodeProperty codeElement, LanguageWriter w case CodePropertyKind.Headers: case CodePropertyKind.Options: case CodePropertyKind.QueryParameter: - conventions.WriteInLineDescription(codeElement.Documentation.Description, writer); + conventions.WriteInLineDescription(codeElement.Documentation.DescriptionTemplate, writer); writer.WriteLine($"{conventions.GetAccessModifier(codeElement.Access)}{codeElement.NamePrefix}{codeElement.Name}: {(codeElement.Type.IsNullable ? "Optional[" : string.Empty)}{returnType}{(codeElement.Type.IsNullable ? "]" : string.Empty)} = None"); writer.WriteLine(); break; diff --git a/src/Kiota.Builder/Writers/Python/PythonConventionService.cs b/src/Kiota.Builder/Writers/Python/PythonConventionService.cs index caa6829fd6..15776a3bfd 100644 --- a/src/Kiota.Builder/Writers/Python/PythonConventionService.cs +++ b/src/Kiota.Builder/Writers/Python/PythonConventionService.cs @@ -176,7 +176,7 @@ public void WriteLongDescription(CodeDocumentation documentation, LanguageWriter { writer.WriteLine(DocCommentStart); if (documentation.DescriptionAvailable) - writer.WriteLine($"{RemoveInvalidDescriptionCharacters(documentation.Description)}"); + writer.WriteLine($"{RemoveInvalidDescriptionCharacters(documentation.DescriptionTemplate)}"); foreach (var additionalRemark in additionalRemarksArray.Where(static x => !string.IsNullOrEmpty(x))) writer.WriteLine($"{additionalRemark}"); if (documentation.ExternalDocumentationAvailable) diff --git a/src/Kiota.Builder/Writers/Ruby/CodeClassDeclarationWriter.cs b/src/Kiota.Builder/Writers/Ruby/CodeClassDeclarationWriter.cs index 4f4d6947a4..f487f14e51 100644 --- a/src/Kiota.Builder/Writers/Ruby/CodeClassDeclarationWriter.cs +++ b/src/Kiota.Builder/Writers/Ruby/CodeClassDeclarationWriter.cs @@ -54,7 +54,7 @@ public override void WriteCodeElement(ClassDeclaration codeElement, LanguageWrit var derivation = codeElement.Inherits == null ? string.Empty : $" < {conventions.GetNormalizedNamespacePrefixForType(codeElement.Inherits)}{codeElement.Inherits.Name.ToFirstCharacterUpperCase()}"; if (codeElement.Parent is CodeClass parentClass) - conventions.WriteShortDescription(parentClass.Documentation.Description, writer); + conventions.WriteShortDescription(parentClass.Documentation.DescriptionTemplate, writer); writer.StartBlock($"class {codeElement.Name.ToFirstCharacterUpperCase()}{derivation}"); var mixins = !codeElement.Implements.Any() ? string.Empty : $"include {codeElement.Implements.Select(static x => x.Name).Aggregate(static (x, y) => x + ", " + y)}"; writer.WriteLine($"{mixins}"); diff --git a/src/Kiota.Builder/Writers/Ruby/CodeEnumWriter.cs b/src/Kiota.Builder/Writers/Ruby/CodeEnumWriter.cs index daaa9f5699..990ec5a4ff 100644 --- a/src/Kiota.Builder/Writers/Ruby/CodeEnumWriter.cs +++ b/src/Kiota.Builder/Writers/Ruby/CodeEnumWriter.cs @@ -16,7 +16,7 @@ public override void WriteCodeElement(CodeEnum codeElement, LanguageWriter write return; if (codeElement.Parent is CodeNamespace ns) conventions.WriteNamespaceModules(ns, writer); - conventions.WriteShortDescription(codeElement.Documentation.Description, writer); + conventions.WriteShortDescription(codeElement.Documentation.DescriptionTemplate, writer); writer.StartBlock($"{codeElement.Name.ToFirstCharacterUpperCase()} = {{"); codeElement.Options.ToList().ForEach(x => writer.WriteLine($"{x.Name.ToFirstCharacterUpperCase()}: :{x.Name.ToFirstCharacterUpperCase()},")); writer.CloseBlock(); diff --git a/src/Kiota.Builder/Writers/Ruby/CodeMethodWriter.cs b/src/Kiota.Builder/Writers/Ruby/CodeMethodWriter.cs index d80ae29ec3..3d9346fa60 100644 --- a/src/Kiota.Builder/Writers/Ruby/CodeMethodWriter.cs +++ b/src/Kiota.Builder/Writers/Ruby/CodeMethodWriter.cs @@ -358,15 +358,15 @@ private void WriteMethodPrototype(CodeMethod code, LanguageWriter writer) } private void WriteMethodDocumentation(CodeMethod code, LanguageWriter writer) { - var isDescriptionPresent = !string.IsNullOrEmpty(code.Documentation.Description); - var parametersWithDescription = code.Parameters.Where(x => !string.IsNullOrEmpty(code.Documentation.Description)).OrderBy(static x => x.Name, StringComparer.OrdinalIgnoreCase).ToArray(); + var isDescriptionPresent = !string.IsNullOrEmpty(code.Documentation.DescriptionTemplate); + var parametersWithDescription = code.Parameters.Where(x => !string.IsNullOrEmpty(code.Documentation.DescriptionTemplate)).OrderBy(static x => x.Name, StringComparer.OrdinalIgnoreCase).ToArray(); if (isDescriptionPresent || parametersWithDescription.Length != 0) { writer.WriteLine(conventions.DocCommentStart); if (isDescriptionPresent) - writer.WriteLine($"{conventions.DocCommentPrefix}{RubyConventionService.RemoveInvalidDescriptionCharacters(code.Documentation.Description)}"); + writer.WriteLine($"{conventions.DocCommentPrefix}{RubyConventionService.RemoveInvalidDescriptionCharacters(code.Documentation.DescriptionTemplate)}"); foreach (var paramWithDescription in parametersWithDescription) - writer.WriteLine($"{conventions.DocCommentPrefix}@param {paramWithDescription.Name.ToSnakeCase()} {RubyConventionService.RemoveInvalidDescriptionCharacters(paramWithDescription.Documentation.Description)}"); + writer.WriteLine($"{conventions.DocCommentPrefix}@param {paramWithDescription.Name.ToSnakeCase()} {RubyConventionService.RemoveInvalidDescriptionCharacters(paramWithDescription.Documentation.DescriptionTemplate)}"); if (code.IsAsync) writer.WriteLine($"{conventions.DocCommentPrefix}@return a Fiber of {code.ReturnType.Name.ToSnakeCase()}"); diff --git a/src/Kiota.Builder/Writers/Ruby/CodePropertyWriter.cs b/src/Kiota.Builder/Writers/Ruby/CodePropertyWriter.cs index f4e2bd074d..12810768c6 100644 --- a/src/Kiota.Builder/Writers/Ruby/CodePropertyWriter.cs +++ b/src/Kiota.Builder/Writers/Ruby/CodePropertyWriter.cs @@ -11,7 +11,7 @@ public override void WriteCodeElement(CodeProperty codeElement, LanguageWriter w ArgumentNullException.ThrowIfNull(codeElement); ArgumentNullException.ThrowIfNull(writer); if (codeElement.ExistsInExternalBaseType) return; - conventions.WriteShortDescription(codeElement.Documentation.Description, writer); + conventions.WriteShortDescription(codeElement.Documentation.DescriptionTemplate, writer); var returnType = conventions.GetTypeString(codeElement.Type, codeElement); if (codeElement.Parent is not CodeClass parentClass) throw new InvalidOperationException("The parent of a property should be a class"); switch (codeElement.Kind) diff --git a/src/Kiota.Builder/Writers/Swift/CodeClassDeclarationWriter.cs b/src/Kiota.Builder/Writers/Swift/CodeClassDeclarationWriter.cs index ae106e1cfd..4843c18437 100644 --- a/src/Kiota.Builder/Writers/Swift/CodeClassDeclarationWriter.cs +++ b/src/Kiota.Builder/Writers/Swift/CodeClassDeclarationWriter.cs @@ -19,7 +19,7 @@ protected override void WriteTypeDeclaration(ClassDeclaration codeElement, Langu .ToArray(); var derivation = derivedTypes.Length != 0 ? ": " + derivedTypes.Select(x => x.ToFirstCharacterUpperCase()).Aggregate(static (x, y) => $"{x}, {y}") + " " : string.Empty; if (codeElement.Parent is CodeClass parentClass) - conventions.WriteShortDescription(parentClass.Documentation.Description, writer); + conventions.WriteShortDescription(parentClass.Documentation.DescriptionTemplate, writer); writer.WriteLine($"public class {codeElement.Name.ToFirstCharacterUpperCase()} {derivation}{{"); writer.IncreaseIndent(); } diff --git a/src/Kiota.Builder/Writers/TypeScript/CodeConstantWriter.cs b/src/Kiota.Builder/Writers/TypeScript/CodeConstantWriter.cs index f18517501a..33a17b55a0 100644 --- a/src/Kiota.Builder/Writers/TypeScript/CodeConstantWriter.cs +++ b/src/Kiota.Builder/Writers/TypeScript/CodeConstantWriter.cs @@ -226,7 +226,7 @@ private void WriteEnumObjectConstant(CodeConstant codeElement, LanguageWriter wr writer.StartBlock($"export const {codeElement.Name.ToFirstCharacterUpperCase()} = {{"); codeEnum.Options.ToList().ForEach(x => { - conventions.WriteShortDescription(x.Documentation.Description, writer); + conventions.WriteShortDescription(x.Documentation.DescriptionTemplate, writer); writer.WriteLine($"{x.Name.ToFirstCharacterUpperCase()}: \"{x.WireName}\","); }); writer.CloseBlock("} as const;"); diff --git a/src/Kiota.Builder/Writers/TypeScript/CodeMethodWriter.cs b/src/Kiota.Builder/Writers/TypeScript/CodeMethodWriter.cs index f90f287497..ca7bab6eab 100644 --- a/src/Kiota.Builder/Writers/TypeScript/CodeMethodWriter.cs +++ b/src/Kiota.Builder/Writers/TypeScript/CodeMethodWriter.cs @@ -42,7 +42,7 @@ internal static void WriteMethodDocumentationInternal(CodeMethod code, LanguageW code.Parameters .Where(static x => x.Documentation.DescriptionAvailable) .OrderBy(static x => x.Name) - .Select(x => $"@param {x.Name} {TypeScriptConventionService.RemoveInvalidDescriptionCharacters(x.Documentation.Description)}") + .Select(x => $"@param {x.Name} {TypeScriptConventionService.RemoveInvalidDescriptionCharacters(x.Documentation.DescriptionTemplate)}") .Union(new[] { returnRemark })); } private static readonly BaseCodeParameterOrderComparer parameterOrderComparer = new(); diff --git a/src/Kiota.Builder/Writers/TypeScript/TypeScriptConventionService.cs b/src/Kiota.Builder/Writers/TypeScript/TypeScriptConventionService.cs index 0c0901e5f4..78b6b61ef1 100644 --- a/src/Kiota.Builder/Writers/TypeScript/TypeScriptConventionService.cs +++ b/src/Kiota.Builder/Writers/TypeScript/TypeScriptConventionService.cs @@ -150,7 +150,7 @@ public void WriteLongDescription(IDocumentedElement documentedElement, LanguageW { writer.WriteLine(DocCommentStart); if (documentedElement.Documentation.DescriptionAvailable) - writer.WriteLine($"{DocCommentPrefix}{RemoveInvalidDescriptionCharacters(documentedElement.Documentation.Description)}"); + writer.WriteLine($"{DocCommentPrefix}{RemoveInvalidDescriptionCharacters(documentedElement.Documentation.DescriptionTemplate)}"); foreach (var additionalRemark in remarks) writer.WriteLine($"{DocCommentPrefix}{additionalRemark}"); diff --git a/tests/Kiota.Builder.Tests/CodeDOM/CodeEnumTests.cs b/tests/Kiota.Builder.Tests/CodeDOM/CodeEnumTests.cs index 54ed7ebd66..1eb403c1b0 100644 --- a/tests/Kiota.Builder.Tests/CodeDOM/CodeEnumTests.cs +++ b/tests/Kiota.Builder.Tests/CodeDOM/CodeEnumTests.cs @@ -16,7 +16,7 @@ public void EnumInits() Name = "Enum", Documentation = new() { - Description = "some description", + DescriptionTemplate = "some description", }, Flags = true, }).First(); diff --git a/tests/Kiota.Builder.Tests/CodeDOM/CodeIndexerTests.cs b/tests/Kiota.Builder.Tests/CodeDOM/CodeIndexerTests.cs index 9828ae870a..b6f8487d3e 100644 --- a/tests/Kiota.Builder.Tests/CodeDOM/CodeIndexerTests.cs +++ b/tests/Kiota.Builder.Tests/CodeDOM/CodeIndexerTests.cs @@ -12,7 +12,7 @@ public void IndexerInits() Name = "idx", Documentation = new() { - Description = "some description", + DescriptionTemplate = "some description", }, ReturnType = new CodeType(), IndexParameter = new() { Name = "param", Type = new CodeType(), } diff --git a/tests/Kiota.Builder.Tests/KiotaBuilderTests.cs b/tests/Kiota.Builder.Tests/KiotaBuilderTests.cs index 228f8886d7..cc0f7850af 100644 --- a/tests/Kiota.Builder.Tests/KiotaBuilderTests.cs +++ b/tests/Kiota.Builder.Tests/KiotaBuilderTests.cs @@ -294,15 +294,15 @@ public async Task ParsesEnumDescriptions() var firstOption = enumDef.Options.First(); Assert.Equal("+1", firstOption.SerializationName); Assert.Equal("plus_1", firstOption.Name); - Assert.Empty(firstOption.Documentation.Description); + Assert.Empty(firstOption.Documentation.DescriptionTemplate); var secondOption = enumDef.Options.ElementAt(1); Assert.Equal("-1", secondOption.SerializationName); Assert.Equal("minus_1", secondOption.Name); - Assert.Empty(secondOption.Documentation.Description); + Assert.Empty(secondOption.Documentation.DescriptionTemplate); var thirdOption = enumDef.Options.ElementAt(2); Assert.Equal("Standard_LRS", thirdOption.SerializationName); Assert.Equal("StandardLocalRedundancy", thirdOption.Name); - Assert.NotEmpty(thirdOption.Documentation.Description); + Assert.NotEmpty(thirdOption.Documentation.DescriptionTemplate); Assert.Single(enumDef.Options.Where(static x => x.Name.Equals("Premium_LRS", StringComparison.OrdinalIgnoreCase))); } @@ -4888,7 +4888,7 @@ public void ModelsDoesntUsePathDescriptionWhenAvailable() Assert.NotNull(modelsNS); var responseClass = modelsNS.Classes.FirstOrDefault(x => x.IsOfKind(CodeClassKind.Model)); Assert.NotNull(responseClass); - Assert.Empty(responseClass.Documentation.Description); + Assert.Empty(responseClass.Documentation.DescriptionTemplate); } [Fact] public void CleansUpInvalidDescriptionCharacters() @@ -4952,7 +4952,7 @@ public void CleansUpInvalidDescriptionCharacters() Assert.NotNull(modelsNS); var responseClass = modelsNS.Classes.FirstOrDefault(x => x.IsOfKind(CodeClassKind.Model)); Assert.NotNull(responseClass); - Assert.Equal("some description with invalid characters: ", responseClass.Documentation.Description); + Assert.Equal("some description with invalid characters: ", responseClass.Documentation.DescriptionTemplate); } [InlineData("application/json")] [InlineData("application/json;odata.metadata=minimal;odata.streaming=true;IEEE754Compatible=false;charset=utf-8")] @@ -5072,7 +5072,7 @@ public void ModelsUseDescriptionWhenAvailable(bool excludeBackwardCompatible) Assert.NotNull(modelsSubNS); var responseClass = modelsSubNS.FindChildByName("AnswerGetResponse", false); Assert.NotNull(responseClass); - Assert.Equal("some description", responseClass.Documentation.Description); + Assert.Equal("some description", responseClass.Documentation.DescriptionTemplate); var obsoleteResponseClass = modelsSubNS.FindChildByName("AnswerResponse", false); if (excludeBackwardCompatible) @@ -5080,13 +5080,13 @@ public void ModelsUseDescriptionWhenAvailable(bool excludeBackwardCompatible) else { Assert.NotNull(obsoleteResponseClass); - Assert.Equal("some description", obsoleteResponseClass.Documentation.Description); + Assert.Equal("some description", obsoleteResponseClass.Documentation.DescriptionTemplate); Assert.True(obsoleteResponseClass.Deprecation.IsDeprecated); } var requestBuilderClass = modelsSubNS.Classes.FirstOrDefault(static c => c.IsOfKind(CodeClassKind.RequestBuilder)); Assert.NotNull(requestBuilderClass); - Assert.Equal("some path item description", requestBuilderClass.Documentation.Description); + Assert.Equal("some path item description", requestBuilderClass.Documentation.DescriptionTemplate); if (excludeBackwardCompatible) Assert.Single(requestBuilderClass.Methods.Where(static x => x.Kind is CodeMethodKind.RequestExecutor)); @@ -5095,7 +5095,7 @@ public void ModelsUseDescriptionWhenAvailable(bool excludeBackwardCompatible) var responseProperty = codeModel.FindNamespaceByName("TestSdk").Classes.SelectMany(c => c.Properties).FirstOrDefault(static p => p.Kind == CodePropertyKind.RequestBuilder); Assert.NotNull(responseProperty); - Assert.Equal("some path item description", responseProperty.Documentation.Description); + Assert.Equal("some path item description", responseProperty.Documentation.DescriptionTemplate); } [Fact] @@ -6219,7 +6219,7 @@ public async Task IndexerAndRequestBuilderNamesMatch() var collectionIndexer = collectionRequestBuilder.Indexer; Assert.NotNull(collectionIndexer); Assert.Equal("string", collectionIndexer.IndexParameter.Type.Name, StringComparer.OrdinalIgnoreCase); - Assert.Equal("Unique identifier of the item", collectionIndexer.IndexParameter.Documentation.Description, StringComparer.OrdinalIgnoreCase); + Assert.Equal("Unique identifier of the item", collectionIndexer.IndexParameter.Documentation.DescriptionTemplate, StringComparer.OrdinalIgnoreCase); Assert.False(collectionIndexer.Deprecation.IsDeprecated); var itemRequestBuilderNamespace = codeModel.FindNamespaceByName("ApiSdk.me.posts.item"); Assert.NotNull(itemRequestBuilderNamespace); @@ -6309,7 +6309,7 @@ public async Task IndexerTypeIsAccurateAndBackwardCompatibleIndexersAreAdded() var postsCollectionIndexer = postsCollectionRequestBuilder.Indexer; Assert.NotNull(postsCollectionIndexer); Assert.Equal("integer", postsCollectionIndexer.IndexParameter.Type.Name); - Assert.Equal("The id of the pet to retrieve", postsCollectionIndexer.IndexParameter.Documentation.Description, StringComparer.OrdinalIgnoreCase); + Assert.Equal("The id of the pet to retrieve", postsCollectionIndexer.IndexParameter.Documentation.DescriptionTemplate, StringComparer.OrdinalIgnoreCase); Assert.False(postsCollectionIndexer.IndexParameter.Type.IsNullable); Assert.False(postsCollectionIndexer.Deprecation.IsDeprecated); var postsCollectionStringIndexer = postsCollectionRequestBuilder.FindChildByName($"{postsCollectionIndexer.Name}-string"); @@ -6328,7 +6328,7 @@ public async Task IndexerTypeIsAccurateAndBackwardCompatibleIndexersAreAdded() var authorsCollectionIndexer = authorsCollectionRequestBuilder.Indexer; Assert.NotNull(authorsCollectionIndexer); Assert.Equal("Guid", authorsCollectionIndexer.IndexParameter.Type.Name); - Assert.Equal("The id of the author's posts to retrieve", authorsCollectionIndexer.IndexParameter.Documentation.Description, StringComparer.OrdinalIgnoreCase); + Assert.Equal("The id of the author's posts to retrieve", authorsCollectionIndexer.IndexParameter.Documentation.DescriptionTemplate, StringComparer.OrdinalIgnoreCase); Assert.False(authorsCollectionIndexer.IndexParameter.Type.IsNullable); Assert.False(authorsCollectionIndexer.Deprecation.IsDeprecated); var authorsCllectionStringIndexer = authorsCollectionRequestBuilder.FindChildByName($"{authorsCollectionIndexer.Name}-string"); @@ -6347,7 +6347,7 @@ public async Task IndexerTypeIsAccurateAndBackwardCompatibleIndexersAreAdded() var actorsCollectionIndexer = actorsCollectionRequestBuilder.Indexer; Assert.NotNull(actorsCollectionIndexer); Assert.Equal("Guid", actorsCollectionIndexer.IndexParameter.Type.Name); - Assert.Equal("The id of the actor", actorsCollectionIndexer.IndexParameter.Documentation.Description, StringComparer.OrdinalIgnoreCase); + Assert.Equal("The id of the actor", actorsCollectionIndexer.IndexParameter.Documentation.DescriptionTemplate, StringComparer.OrdinalIgnoreCase); Assert.False(actorsCollectionIndexer.IndexParameter.Type.IsNullable); Assert.False(actorsCollectionIndexer.Deprecation.IsDeprecated); var actorsCllectionStringIndexer = actorsCollectionRequestBuilder.FindChildByName($"{actorsCollectionIndexer.Name}-string"); @@ -6922,10 +6922,10 @@ public async Task DescriptionTakenFromAllOf() var document = await builder.CreateOpenApiDocumentAsync(fs); var node = builder.CreateUriSpace(document); var codeModel = builder.CreateSourceModel(node); - Assert.Equal("base entity", codeModel.FindChildByName("entity").Documentation.Description); - Assert.Equal("directory object", codeModel.FindChildByName("directoryObject").Documentation.Description); - Assert.Equal("sub1", codeModel.FindChildByName("sub1").Documentation.Description); - Assert.Equal("sub2", codeModel.FindChildByName("sub2").Documentation.Description); + Assert.Equal("base entity", codeModel.FindChildByName("entity").Documentation.DescriptionTemplate); + Assert.Equal("directory object", codeModel.FindChildByName("directoryObject").Documentation.DescriptionTemplate); + Assert.Equal("sub1", codeModel.FindChildByName("sub1").Documentation.DescriptionTemplate); + Assert.Equal("sub2", codeModel.FindChildByName("sub2").Documentation.DescriptionTemplate); } [Fact] public async Task CleanupSymbolNameDoesNotCauseNameConflicts() diff --git a/tests/Kiota.Builder.Tests/Refiners/CSharpLanguageRefinerTests.cs b/tests/Kiota.Builder.Tests/Refiners/CSharpLanguageRefinerTests.cs index e965caa613..85e263c2f3 100644 --- a/tests/Kiota.Builder.Tests/Refiners/CSharpLanguageRefinerTests.cs +++ b/tests/Kiota.Builder.Tests/Refiners/CSharpLanguageRefinerTests.cs @@ -435,7 +435,7 @@ public async Task KeepsCancellationParametersInRequestExecutors() Kind = CodeParameterKind.Cancellation, Documentation = new() { - Description = "Cancellation token to use when cancelling requests", + DescriptionTemplate = "Cancellation token to use when cancelling requests", }, Type = new CodeType { Name = "CancellationToken", IsExternal = true }, }; diff --git a/tests/Kiota.Builder.Tests/Refiners/GoLanguageRefinerTests.cs b/tests/Kiota.Builder.Tests/Refiners/GoLanguageRefinerTests.cs index 49c0e45252..3d7d08a7f0 100644 --- a/tests/Kiota.Builder.Tests/Refiners/GoLanguageRefinerTests.cs +++ b/tests/Kiota.Builder.Tests/Refiners/GoLanguageRefinerTests.cs @@ -663,7 +663,7 @@ public async Task RenamesCancellationParametersInRequestExecutors() Kind = CodeParameterKind.Cancellation, Documentation = new() { - Description = "Cancellation token to use when cancelling requests", + DescriptionTemplate = "Cancellation token to use when cancelling requests", }, Type = new CodeType { Name = "CancelletionToken", IsExternal = true }, }; diff --git a/tests/Kiota.Builder.Tests/Refiners/JavaLanguageRefinerTests.cs b/tests/Kiota.Builder.Tests/Refiners/JavaLanguageRefinerTests.cs index e81a45548d..b8416e1fc5 100644 --- a/tests/Kiota.Builder.Tests/Refiners/JavaLanguageRefinerTests.cs +++ b/tests/Kiota.Builder.Tests/Refiners/JavaLanguageRefinerTests.cs @@ -396,7 +396,7 @@ public async Task DoesNotKeepCancellationParametersInRequestExecutors() Kind = CodeParameterKind.Cancellation, Documentation = new() { - Description = "Cancellation token to use when cancelling requests", + DescriptionTemplate = "Cancellation token to use when cancelling requests", }, Type = new CodeType { Name = "CancelletionToken", IsExternal = true }, }; diff --git a/tests/Kiota.Builder.Tests/Refiners/PythonLanguageRefinerTests.cs b/tests/Kiota.Builder.Tests/Refiners/PythonLanguageRefinerTests.cs index 5c37b2ce5d..432f17db69 100644 --- a/tests/Kiota.Builder.Tests/Refiners/PythonLanguageRefinerTests.cs +++ b/tests/Kiota.Builder.Tests/Refiners/PythonLanguageRefinerTests.cs @@ -535,7 +535,7 @@ public async Task DoesNotKeepCancellationParametersInRequestExecutors() Kind = CodeParameterKind.Cancellation, Documentation = new() { - Description = "Cancellation token to use when cancelling requests", + DescriptionTemplate = "Cancellation token to use when cancelling requests", }, Type = new CodeType { Name = "CancellationToken", IsExternal = true }, }; diff --git a/tests/Kiota.Builder.Tests/Refiners/RubyLanguageRefinerTests.cs b/tests/Kiota.Builder.Tests/Refiners/RubyLanguageRefinerTests.cs index 62539c1fdb..fc0957ceec 100644 --- a/tests/Kiota.Builder.Tests/Refiners/RubyLanguageRefinerTests.cs +++ b/tests/Kiota.Builder.Tests/Refiners/RubyLanguageRefinerTests.cs @@ -49,7 +49,7 @@ public async Task DoesNotKeepCancellationParametersInRequestExecutors() Kind = CodeParameterKind.Cancellation, Documentation = new() { - Description = "Cancellation token to use when cancelling requests", + DescriptionTemplate = "Cancellation token to use when cancelling requests", }, Type = new CodeType { Name = "CancellationToken", IsExternal = true }, }; diff --git a/tests/Kiota.Builder.Tests/Refiners/TypeScriptLanguageRefinerTests.cs b/tests/Kiota.Builder.Tests/Refiners/TypeScriptLanguageRefinerTests.cs index accd0ea3a6..b3030025e0 100644 --- a/tests/Kiota.Builder.Tests/Refiners/TypeScriptLanguageRefinerTests.cs +++ b/tests/Kiota.Builder.Tests/Refiners/TypeScriptLanguageRefinerTests.cs @@ -602,7 +602,7 @@ public async Task DoesNotKeepCancellationParametersInRequestExecutors() Kind = CodeParameterKind.Cancellation, Documentation = new() { - Description = "Cancellation token to use when cancelling requests", + DescriptionTemplate = "Cancellation token to use when cancelling requests", }, Type = new CodeType { Name = "CancellationToken", IsExternal = true }, }; diff --git a/tests/Kiota.Builder.Tests/Writers/CLI/CliCodeMethodWriterTests.cs b/tests/Kiota.Builder.Tests/Writers/CLI/CliCodeMethodWriterTests.cs index a9e8a8f7ac..c211a7121c 100644 --- a/tests/Kiota.Builder.Tests/Writers/CLI/CliCodeMethodWriterTests.cs +++ b/tests/Kiota.Builder.Tests/Writers/CLI/CliCodeMethodWriterTests.cs @@ -134,7 +134,7 @@ private static void AddPathQueryAndHeaderParameters(CodeMethod method) DefaultValue = "test", Documentation = new() { - Description = "The q option", + DescriptionTemplate = "The q option", }, Optional = true }); @@ -151,7 +151,7 @@ private static void AddPathQueryAndHeaderParameters(CodeMethod method) Type = stringType, Documentation = new() { - Description = "The test header", + DescriptionTemplate = "The test header", }, }); } @@ -252,7 +252,7 @@ public void WritesIndexerCommands() public void WritesMatchingIndexerCommandsIntoExecutableCommand() { method.Kind = CodeMethodKind.CommandBuilder; - method.Documentation.Description = "Test description"; + method.Documentation.DescriptionTemplate = "Test description"; method.SimpleName = "User"; method.HttpMethod = HttpMethod.Get; var stringType = new CodeType @@ -438,7 +438,7 @@ public void WritesMatchingIndexerCommandsIntoContainerCommand() public void WritesExecutableCommandThatReusesMatchingNavCommandInstance() { method.Kind = CodeMethodKind.CommandBuilder; - method.Documentation.Description = "Test description"; + method.Documentation.DescriptionTemplate = "Test description"; method.SimpleName = "User"; method.HttpMethod = HttpMethod.Get; var stringType = new CodeType { Name = "string" }; @@ -715,7 +715,7 @@ public void WritesContainerCommandWithConflictingTypes() public void WritesExecutableCommandWithRelatedLinksInDescription() { method.Kind = CodeMethodKind.CommandBuilder; - method.Documentation.Description = "Test description"; + method.Documentation.DescriptionTemplate = "Test description"; method.Documentation.DocumentationLink = new Uri("https://test.com/help/description"); method.SimpleName = "User"; method.HttpMethod = HttpMethod.Get; @@ -768,7 +768,7 @@ public void WritesExecutableCommandWithRelatedLinksInDescription() }, Documentation = new() { - Description = "Documentation label2", + DescriptionTemplate = "Documentation label2", DocumentationLink = new Uri("https://test.com/help/description") } }); @@ -783,7 +783,7 @@ public void WritesExecutableCommandWithRelatedLinksInDescription() }, Documentation = new() { - Description = "Documentation label3", + DescriptionTemplate = "Documentation label3", DocumentationLabel = "Test label", DocumentationLink = new Uri("https://test.com/help/description") } @@ -823,7 +823,7 @@ public void WritesExecutableCommandWithRelatedLinksInDescription() public void WritesExecutableCommandForGetRequestPrimitive() { method.Kind = CodeMethodKind.CommandBuilder; - method.Documentation.Description = "Test description"; + method.Documentation.DescriptionTemplate = "Test description"; method.SimpleName = "User"; method.HttpMethod = HttpMethod.Get; var stringType = new CodeType @@ -893,7 +893,7 @@ public void WritesExecutableCommandForPagedGetRequestModel() { method.Kind = CodeMethodKind.CommandBuilder; - method.Documentation.Description = "Test description"; + method.Documentation.DescriptionTemplate = "Test description"; method.SimpleName = "User"; method.HttpMethod = HttpMethod.Get; var userClass = root.AddClass(new CodeClass @@ -966,7 +966,7 @@ public void WritesExecutableCommandForGetRequestModel() { method.Kind = CodeMethodKind.CommandBuilder; - method.Documentation.Description = "Test description"; + method.Documentation.DescriptionTemplate = "Test description"; method.SimpleName = "User"; method.HttpMethod = HttpMethod.Get; var userClass = root.AddClass(new CodeClass @@ -1142,7 +1142,7 @@ public void WritesExecutableCommandForPostRequestWithModelBodyAndContentType() Name = "contentType", Kind = CodeParameterKind.RequestBodyContentType, Type = stringType, - Documentation = new() { Description = "The request content type." }, + Documentation = new() { DescriptionTemplate = "The request content type." }, PossibleValues = new List { "application/json", "text/plain" } }; method.OriginalMethod.AddParameter(contentTypeParam); diff --git a/tests/Kiota.Builder.Tests/Writers/CSharp/CodeEnumWriterTests.cs b/tests/Kiota.Builder.Tests/Writers/CSharp/CodeEnumWriterTests.cs index b68301d0f5..e5e6590f4f 100644 --- a/tests/Kiota.Builder.Tests/Writers/CSharp/CodeEnumWriterTests.cs +++ b/tests/Kiota.Builder.Tests/Writers/CSharp/CodeEnumWriterTests.cs @@ -113,11 +113,11 @@ public void WritesFlagsEnum() [Fact] public void WritesEnumOptionDescription() { - Option.Documentation.Description = "Some option description"; + Option.Documentation.DescriptionTemplate = "Some option description"; currentEnum.AddOption(Option); writer.Write(currentEnum); var result = tw.ToString(); - Assert.Contains($"{Option.Documentation.Description}", result); + Assert.Contains($"{Option.Documentation.DescriptionTemplate}", result); AssertExtensions.CurlyBracesAreClosed(result, 1); } [Fact] diff --git a/tests/Kiota.Builder.Tests/Writers/CSharp/CodeIndexerWriterTests.cs b/tests/Kiota.Builder.Tests/Writers/CSharp/CodeIndexerWriterTests.cs index cdaad32402..93bec8f238 100644 --- a/tests/Kiota.Builder.Tests/Writers/CSharp/CodeIndexerWriterTests.cs +++ b/tests/Kiota.Builder.Tests/Writers/CSharp/CodeIndexerWriterTests.cs @@ -43,7 +43,7 @@ public CodeIndexerWriterTests() SerializationName = "id", Documentation = new() { - Description = "some description" + DescriptionTemplate = "some description" } } }; diff --git a/tests/Kiota.Builder.Tests/Writers/CSharp/CodeMethodWriterTests.cs b/tests/Kiota.Builder.Tests/Writers/CSharp/CodeMethodWriterTests.cs index 341ce241d3..bb15cda15e 100644 --- a/tests/Kiota.Builder.Tests/Writers/CSharp/CodeMethodWriterTests.cs +++ b/tests/Kiota.Builder.Tests/Writers/CSharp/CodeMethodWriterTests.cs @@ -1232,12 +1232,12 @@ public void WritesSerializerBody() public void WritesMethodAsyncDescription() { setup(); - method.Documentation.Description = MethodDescription; + method.Documentation.DescriptionTemplate = MethodDescription; var parameter = new CodeParameter { Documentation = new() { - Description = ParamDescription + DescriptionTemplate = ParamDescription }, Name = ParamName, Type = new CodeType @@ -1261,13 +1261,13 @@ public void WritesMethodAsyncDescription() public void WritesMethodSyncDescription() { setup(); - method.Documentation.Description = MethodDescription; + method.Documentation.DescriptionTemplate = MethodDescription; method.IsAsync = false; var parameter = new CodeParameter { Documentation = new() { - Description = ParamDescription + DescriptionTemplate = ParamDescription }, Name = ParamName, Type = new CodeType @@ -1285,7 +1285,7 @@ public void WritesMethodSyncDescription() public void WritesMethodDescriptionLink() { setup(); - method.Documentation.Description = MethodDescription; + method.Documentation.DescriptionTemplate = MethodDescription; method.Documentation.DocumentationLabel = "see more"; method.Documentation.DocumentationLink = new("https://foo.org/docs"); method.IsAsync = false; @@ -1293,7 +1293,7 @@ public void WritesMethodDescriptionLink() { Documentation = new() { - Description = ParamDescription, + DescriptionTemplate = ParamDescription, }, Name = ParamName, Type = new CodeType diff --git a/tests/Kiota.Builder.Tests/Writers/Go/CodeEnumWriterTests.cs b/tests/Kiota.Builder.Tests/Writers/Go/CodeEnumWriterTests.cs index dec80b3e33..91b0c5514f 100644 --- a/tests/Kiota.Builder.Tests/Writers/Go/CodeEnumWriterTests.cs +++ b/tests/Kiota.Builder.Tests/Writers/Go/CodeEnumWriterTests.cs @@ -128,14 +128,14 @@ public void WritesEnumOptionDescription() { Documentation = new() { - Description = "Some option description", + DescriptionTemplate = "Some option description", }, Name = "option1", }; currentEnum.AddOption(option); writer.Write(currentEnum); var result = tw.ToString(); - Assert.Contains($"// {option.Documentation.Description}", result); + Assert.Contains($"// {option.Documentation.DescriptionTemplate}", result); AssertExtensions.CurlyBracesAreClosed(result); } } diff --git a/tests/Kiota.Builder.Tests/Writers/Go/CodeMethodWriterTests.cs b/tests/Kiota.Builder.Tests/Writers/Go/CodeMethodWriterTests.cs index fc905bcb8d..cda1087fd7 100644 --- a/tests/Kiota.Builder.Tests/Writers/Go/CodeMethodWriterTests.cs +++ b/tests/Kiota.Builder.Tests/Writers/Go/CodeMethodWriterTests.cs @@ -1563,13 +1563,13 @@ public void WritesSerializerBackingStoreBody() public void WritesMethodSyncDescription() { setup(); - method.Documentation.Description = MethodDescription; + method.Documentation.DescriptionTemplate = MethodDescription; method.IsAsync = false; var parameter = new CodeParameter { Documentation = new() { - Description = ParamDescription + DescriptionTemplate = ParamDescription }, Name = ParamName, Type = new CodeType @@ -1587,7 +1587,7 @@ public void WritesMethodSyncDescription() public void WritesMethodDescriptionLink() { setup(); - method.Documentation.Description = MethodDescription; + method.Documentation.DescriptionTemplate = MethodDescription; method.Documentation.DocumentationLabel = "see more"; method.Documentation.DocumentationLink = new("https://foo.org/docs"); method.IsAsync = false; @@ -1595,7 +1595,7 @@ public void WritesMethodDescriptionLink() { Documentation = new() { - Description = ParamDescription, + DescriptionTemplate = ParamDescription, }, Name = ParamName, Type = new CodeType @@ -1748,7 +1748,7 @@ public void WritesDescription() Name = "string" } }); - method.Documentation.Description = "Some description"; + method.Documentation.DescriptionTemplate = "Some description"; writer.Write(method); var result = tw.ToString(); Assert.Contains($"// {method.Name.ToFirstCharacterUpperCase()} some description", result); diff --git a/tests/Kiota.Builder.Tests/Writers/Java/CodeEnumWriterTests.cs b/tests/Kiota.Builder.Tests/Writers/Java/CodeEnumWriterTests.cs index 04d4fd02b2..16138b6bc0 100644 --- a/tests/Kiota.Builder.Tests/Writers/Java/CodeEnumWriterTests.cs +++ b/tests/Kiota.Builder.Tests/Writers/Java/CodeEnumWriterTests.cs @@ -68,14 +68,14 @@ public void WritesEnumOptionDescription() { Documentation = new() { - Description = "Some option description", + DescriptionTemplate = "Some option description", }, Name = "option1", }; currentEnum.AddOption(option); writer.Write(currentEnum); var result = tw.ToString(); - Assert.Contains($"/** {option.Documentation.Description} */", result); + Assert.Contains($"/** {option.Documentation.DescriptionTemplate} */", result); AssertExtensions.CurlyBracesAreClosed(result); } [Fact] diff --git a/tests/Kiota.Builder.Tests/Writers/Java/CodeMethodWriterTests.cs b/tests/Kiota.Builder.Tests/Writers/Java/CodeMethodWriterTests.cs index 8a81d8ea2f..635df542a1 100644 --- a/tests/Kiota.Builder.Tests/Writers/Java/CodeMethodWriterTests.cs +++ b/tests/Kiota.Builder.Tests/Writers/Java/CodeMethodWriterTests.cs @@ -1490,13 +1490,13 @@ public void WritesSerializerBody() public void WritesMethodSyncDescription() { setup(); - method.Documentation.Description = MethodDescription; + method.Documentation.DescriptionTemplate = MethodDescription; method.IsAsync = false; var parameter = new CodeParameter { Documentation = new() { - Description = ParamDescription, + DescriptionTemplate = ParamDescription, }, Name = ParamName, Type = new CodeType @@ -1514,7 +1514,7 @@ public void WritesMethodSyncDescription() public void WritesMethodDescriptionLink() { setup(); - method.Documentation.Description = MethodDescription; + method.Documentation.DescriptionTemplate = MethodDescription; method.Documentation.DocumentationLabel = "see more"; method.Documentation.DocumentationLink = new("https://foo.org/docs"); method.IsAsync = false; @@ -1522,7 +1522,7 @@ public void WritesMethodDescriptionLink() { Documentation = new() { - Description = ParamDescription, + DescriptionTemplate = ParamDescription, }, Name = ParamName, Type = new CodeType diff --git a/tests/Kiota.Builder.Tests/Writers/Php/CodeClassDeclarationWriterTests.cs b/tests/Kiota.Builder.Tests/Writers/Php/CodeClassDeclarationWriterTests.cs index ef44985410..ba823a0e42 100644 --- a/tests/Kiota.Builder.Tests/Writers/Php/CodeClassDeclarationWriterTests.cs +++ b/tests/Kiota.Builder.Tests/Writers/Php/CodeClassDeclarationWriterTests.cs @@ -170,7 +170,7 @@ public async Task AddsImportsToRequestConfigClasses() Kind = CodePropertyKind.QueryParameter, Documentation = new() { - Description = "Filter by start time", + DescriptionTemplate = "Filter by start time", }, Type = new CodeType { @@ -183,7 +183,7 @@ public async Task AddsImportsToRequestConfigClasses() Kind = CodePropertyKind.QueryParameter, Documentation = new() { - Description = "Filter by end time", + DescriptionTemplate = "Filter by end time", }, Type = new CodeType { @@ -196,7 +196,7 @@ public async Task AddsImportsToRequestConfigClasses() Kind = CodePropertyKind.QueryParameter, Documentation = new() { - Description = "Filter by start date", + DescriptionTemplate = "Filter by start date", }, Type = new CodeType { @@ -209,7 +209,7 @@ public async Task AddsImportsToRequestConfigClasses() Kind = CodePropertyKind.QueryParameter, Documentation = new() { - Description = "Filter by status", + DescriptionTemplate = "Filter by status", }, Type = new CodeType { @@ -225,7 +225,7 @@ public async Task AddsImportsToRequestConfigClasses() { Name = "queryParameters", Kind = CodePropertyKind.QueryParameters, - Documentation = new() { Description = "Request query parameters", }, + Documentation = new() { DescriptionTemplate = "Request query parameters", }, Type = new CodeType { Name = queryParamClass.Name, TypeDefinition = queryParamClass }, } }); diff --git a/tests/Kiota.Builder.Tests/Writers/Php/CodeMethodWriterTests.cs b/tests/Kiota.Builder.Tests/Writers/Php/CodeMethodWriterTests.cs index 2c5646218d..f9fa005b23 100644 --- a/tests/Kiota.Builder.Tests/Writers/Php/CodeMethodWriterTests.cs +++ b/tests/Kiota.Builder.Tests/Writers/Php/CodeMethodWriterTests.cs @@ -79,7 +79,7 @@ private void setup(bool withInheritance = false) IsAsync = true, Documentation = new() { - Description = "This is a very good method to try all the good things", + DescriptionTemplate = "This is a very good method to try all the good things", }, ReturnType = new CodeType { @@ -100,7 +100,7 @@ private void AddRequestProperties() DefaultValue = "https://graph.microsoft.com/v1.0/", Documentation = new() { - Description = "The URL template", + DescriptionTemplate = "The URL template", }, Kind = CodePropertyKind.UrlTemplate, Type = new CodeType { Name = "string" } @@ -112,7 +112,7 @@ private void AddRequestProperties() DefaultValue = "[]", Documentation = new() { - Description = "The Path parameters.", + DescriptionTemplate = "The Path parameters.", }, Kind = CodePropertyKind.PathParameters, Type = new CodeType { Name = "array" } @@ -123,7 +123,7 @@ private void AddRequestProperties() Access = AccessModifier.Protected, Documentation = new() { - Description = "The request Adapter", + DescriptionTemplate = "The request Adapter", }, Kind = CodePropertyKind.RequestAdapter, Type = new CodeType @@ -213,7 +213,7 @@ public void WriteABasicMethod() public void WriteMethodWithNoDescription() { setup(); - method.Documentation.Description = string.Empty; + method.Documentation.DescriptionTemplate = string.Empty; _codeMethodWriter.WriteCodeElement(method, languageWriter); var result = stringWriter.ToString(); @@ -248,7 +248,7 @@ public async Task WriteRequestExecutor() }, Documentation = new() { - Description = "This will send a POST request", + DescriptionTemplate = "This will send a POST request", DocumentationLink = new Uri("https://learn.microsoft.com/"), DocumentationLabel = "Learning" }, @@ -342,7 +342,7 @@ public async Task WritesRequestExecutorForEnumTypes() }, Documentation = new() { - Description = "This will send a POST request", + DescriptionTemplate = "This will send a POST request", DocumentationLink = new Uri("https://learn.microsoft.com/"), DocumentationLabel = "Learning" }, @@ -410,7 +410,7 @@ public async Task WritesRequestExecutorForEnumTypes() { Name = "Status", Documentation = new() { - Description = "Status Enum", + DescriptionTemplate = "Status Enum", }, }}, Access = AccessModifier.Private }, "$writer->writeEnumValue('status', $this->getStatus());" @@ -421,7 +421,7 @@ public async Task WritesRequestExecutorForEnumTypes() { Name = "Architecture", CollectionKind = CodeTypeBase.CodeTypeCollectionKind.Array, TypeDefinition = new CodeEnum { Name = "Architecture", Documentation = new() { - Description = "Arch Enum, accepts x64, x86, hybrid" + DescriptionTemplate = "Arch Enum, accepts x64, x86, hybrid" }, } }, Access = AccessModifier.Private, Kind = CodePropertyKind.Custom }, @@ -736,7 +736,7 @@ public async Task WriteIndexerBody() Kind = CodeMethodKind.IndexerBackwardCompatibility, Documentation = new() { - Description = "Get messages by a specific ID.", + DescriptionTemplate = "Get messages by a specific ID.", }, OriginalIndexer = new CodeIndexer { @@ -838,7 +838,7 @@ public async Task WriteIndexerBody() { Name = "EmailAddress", Kind = CodeClassKind.Model, Documentation = new() { - Description = "Email", + DescriptionTemplate = "Email", }, Parent = GetParentClassInStaticContext() }, CollectionKind = CodeTypeBase.CodeTypeCollectionKind.Array }, Access = AccessModifier.Private}, "'users' => fn(ParseNode $n) => $o->setUsers($n->getCollectionOfObjectValues([EmailAddress::class, 'createFromDiscriminatorValue']))," @@ -873,7 +873,7 @@ public async Task WriteDeserializer(CodeProperty property, params string[] expec Kind = CodeMethodKind.Deserializer, Documentation = new() { - Description = "Just some random method", + DescriptionTemplate = "Just some random method", }, ReturnType = new CodeType { @@ -1049,7 +1049,7 @@ public async Task WriteDeserializerMergeWhenHasParent() Kind = CodeMethodKind.Deserializer, Documentation = new() { - Description = "Just some random method", + DescriptionTemplate = "Just some random method", }, ReturnType = new CodeType { @@ -1077,7 +1077,7 @@ public async Task WriteConstructorBody() Access = AccessModifier.Public, Documentation = new() { - Description = "The constructor for this class", + DescriptionTemplate = "The constructor for this class", }, ReturnType = new CodeType { Name = "void" }, Kind = CodeMethodKind.Constructor @@ -1165,7 +1165,7 @@ public void WriteGetter() Name = "getEmailAddress", Documentation = new() { - Description = "This method gets the emailAddress", + DescriptionTemplate = "This method gets the emailAddress", }, ReturnType = new CodeType { @@ -1619,7 +1619,7 @@ public async Task WritesApiClientWithBackingStoreConstructor() Optional = true, Documentation = new() { - Description = "The backing store to use for the models.", + DescriptionTemplate = "The backing store to use for the models.", }, Kind = CodeParameterKind.BackingStore, Type = new CodeType @@ -1670,7 +1670,7 @@ public async Task WritesModelWithBackingStoreConstructor() Access = AccessModifier.Public, Documentation = new() { - Description = "The constructor for this class", + DescriptionTemplate = "The constructor for this class", }, ReturnType = new CodeType { Name = "void" }, Kind = CodeMethodKind.Constructor @@ -2292,7 +2292,7 @@ public async Task WritesRequestConfigurationConstructor() { Name = "queryParameters", Kind = CodePropertyKind.QueryParameters, - Documentation = new() { Description = "Request query parameters", }, + Documentation = new() { DescriptionTemplate = "Request query parameters", }, Type = new CodeType { Name = queryParamClass.Name, TypeDefinition = queryParamClass }, }, new CodeProperty @@ -2300,14 +2300,14 @@ public async Task WritesRequestConfigurationConstructor() Name = "headers", Access = AccessModifier.Public, Kind = CodePropertyKind.Headers, - Documentation = new() { Description = "Request headers", }, + Documentation = new() { DescriptionTemplate = "Request headers", }, Type = new CodeType { Name = "RequestHeaders", IsExternal = true }, }, new CodeProperty { Name = "options", Kind = CodePropertyKind.Options, - Documentation = new() { Description = "Request options", }, + Documentation = new() { DescriptionTemplate = "Request options", }, Type = new CodeType { Name = "IList", IsExternal = true }, } }); @@ -2336,21 +2336,21 @@ public async Task WritesQueryParameterFactoryMethod() { Name = "select", Kind = CodePropertyKind.QueryParameter, - Documentation = new() { Description = "Select properties to be returned", }, + Documentation = new() { DescriptionTemplate = "Select properties to be returned", }, Type = new CodeType { Name = "string", CollectionKind = CodeTypeBase.CodeTypeCollectionKind.Array }, }, new CodeProperty { Name = "count", Kind = CodePropertyKind.QueryParameter, - Documentation = new() { Description = "Include count of items", }, + Documentation = new() { DescriptionTemplate = "Include count of items", }, Type = new CodeType { Name = "boolean" }, }, new CodeProperty { Name = "top", Kind = CodePropertyKind.QueryParameter, - Documentation = new() { Description = "Show only the first n items", }, + Documentation = new() { DescriptionTemplate = "Show only the first n items", }, Type = new CodeType { Name = "integer" }, } }); @@ -2361,7 +2361,7 @@ public async Task WritesQueryParameterFactoryMethod() { Name = "queryParameters", Kind = CodePropertyKind.QueryParameters, - Documentation = new() { Description = "Request query parameters", }, + Documentation = new() { DescriptionTemplate = "Request query parameters", }, Type = new CodeType { Name = queryParamClass.Name, TypeDefinition = queryParamClass }, } }); @@ -2386,21 +2386,21 @@ public async Task WritesQueryParameterConstructor() { Name = "select", Kind = CodePropertyKind.QueryParameter, - Documentation = new() { Description = "Select properties to be returned", }, + Documentation = new() { DescriptionTemplate = "Select properties to be returned", }, Type = new CodeType { Name = "string", CollectionKind = CodeTypeBase.CodeTypeCollectionKind.Array }, }, new CodeProperty { Name = "count", Kind = CodePropertyKind.QueryParameter, - Documentation = new() { Description = "Include count of items", }, + Documentation = new() { DescriptionTemplate = "Include count of items", }, Type = new CodeType { Name = "boolean" }, }, new CodeProperty { Name = "Top", Kind = CodePropertyKind.QueryParameter, - Documentation = new() { Description = "Show only the first n items", }, + Documentation = new() { DescriptionTemplate = "Show only the first n items", }, Type = new CodeType { Name = "integer" }, } }); diff --git a/tests/Kiota.Builder.Tests/Writers/Php/CodePropertyWriterTests.cs b/tests/Kiota.Builder.Tests/Writers/Php/CodePropertyWriterTests.cs index 22c125f34b..35d7d1565d 100644 --- a/tests/Kiota.Builder.Tests/Writers/Php/CodePropertyWriterTests.cs +++ b/tests/Kiota.Builder.Tests/Writers/Php/CodePropertyWriterTests.cs @@ -32,7 +32,7 @@ public CodePropertyWriterTests() Name = "ParentClass", Documentation = new() { - Description = "This is an amazing class", + DescriptionTemplate = "This is an amazing class", }, Kind = CodeClassKind.Model }; @@ -68,7 +68,7 @@ public void WritePropertyRequestBuilder() Access = AccessModifier.Public, Documentation = new() { - Description = "I can get your messages.", + DescriptionTemplate = "I can get your messages.", }, Type = new CodeType { @@ -91,7 +91,7 @@ public async Task WriteCollectionKindProperty() { Documentation = new() { - Description = "Additional data dictionary", + DescriptionTemplate = "Additional data dictionary", }, Name = "additionalData", Kind = CodePropertyKind.AdditionalData, diff --git a/tests/Kiota.Builder.Tests/Writers/Python/CodeMethodWriterTests.cs b/tests/Kiota.Builder.Tests/Writers/Python/CodeMethodWriterTests.cs index f7b8b52117..70210d6f6e 100644 --- a/tests/Kiota.Builder.Tests/Writers/Python/CodeMethodWriterTests.cs +++ b/tests/Kiota.Builder.Tests/Writers/Python/CodeMethodWriterTests.cs @@ -945,14 +945,14 @@ public void WritesSerializerBody() public void WritesMethodAsyncDescription() { setup(); - method.Documentation.Description = MethodDescription; + method.Documentation.DescriptionTemplate = MethodDescription; method.Documentation.DocumentationLabel = "see more"; method.Documentation.DocumentationLink = new("https://example.org/docs"); var parameter = new CodeParameter { Documentation = new() { - Description = ParamDescription, + DescriptionTemplate = ParamDescription, }, Name = ParamName, Type = new CodeType @@ -976,7 +976,7 @@ public void WritesMethodAsyncDescription() public void WritesMethodSyncDescription() { setup(); - method.Documentation.Description = MethodDescription; + method.Documentation.DescriptionTemplate = MethodDescription; method.Documentation.DocumentationLabel = "see more"; method.Documentation.DocumentationLink = new("https://example.org/docs"); method.IsAsync = false; @@ -984,7 +984,7 @@ public void WritesMethodSyncDescription() { Documentation = new() { - Description = ParamDescription, + DescriptionTemplate = ParamDescription, }, Name = ParamName, Type = new CodeType @@ -1517,7 +1517,7 @@ public void WritesConstructor() Kind = CodePropertyKind.Custom, Documentation = new() { - Description = "This property has a description", + DescriptionTemplate = "This property has a description", }, Type = new CodeType { @@ -1569,7 +1569,7 @@ public void WritesConstructorForRequestBuilder() Kind = CodePropertyKind.UrlTemplate, Documentation = new() { - Description = "This property has a description", + DescriptionTemplate = "This property has a description", }, Type = new CodeType { @@ -1600,7 +1600,7 @@ public void WritesConstructorForRequestBuilderWithRequestAdapter() Kind = CodePropertyKind.UrlTemplate, Documentation = new() { - Description = "This property has a description", + DescriptionTemplate = "This property has a description", }, Type = new CodeType { @@ -1642,7 +1642,7 @@ public void WritesConstructorForRequestBuilderWithRequestAdapterAndPathParameter Kind = CodePropertyKind.UrlTemplate, Documentation = new() { - Description = "This property has a description", + DescriptionTemplate = "This property has a description", }, Type = new CodeType { @@ -1710,7 +1710,7 @@ public void DoesntWriteConstructorForModelClasses() Kind = CodePropertyKind.AdditionalData, Documentation = new() { - Description = "This property has a description", + DescriptionTemplate = "This property has a description", }, Type = new CodeType { @@ -1761,7 +1761,7 @@ public void WritesModelClassesWithDefaultEnumValue() Kind = CodePropertyKind.Custom, Documentation = new() { - Description = "This property has a description", + DescriptionTemplate = "This property has a description", }, Type = new CodeType { @@ -1845,7 +1845,7 @@ public void WritesConstructorWithInheritance() Kind = CodePropertyKind.Custom, Documentation = new() { - Description = "This property has a description", + DescriptionTemplate = "This property has a description", }, Type = new CodeType { @@ -1862,7 +1862,7 @@ public void WritesConstructorWithInheritance() Kind = CodePropertyKind.UrlTemplate, Documentation = new() { - Description = "This property has a description", + DescriptionTemplate = "This property has a description", }, Type = new CodeType { diff --git a/tests/Kiota.Builder.Tests/Writers/Python/CodePropertyWriterTests.cs b/tests/Kiota.Builder.Tests/Writers/Python/CodePropertyWriterTests.cs index 2831a01cdf..46e354959b 100644 --- a/tests/Kiota.Builder.Tests/Writers/Python/CodePropertyWriterTests.cs +++ b/tests/Kiota.Builder.Tests/Writers/Python/CodePropertyWriterTests.cs @@ -81,7 +81,7 @@ public void Dispose() public void WritesRequestBuilder() { property.Kind = CodePropertyKind.RequestBuilder; - property.Documentation.Description = "This is a request builder"; + property.Documentation.DescriptionTemplate = "This is a request builder"; writer.Write(property); var result = tw.ToString(); Assert.Contains("@property", result); @@ -126,7 +126,7 @@ public void WritePrimaryErrorMessagePropertyOption2() var cls = new CodeClass { Name = "MainError", - Documentation = new CodeDocumentation { Description = "Some documentation" } + Documentation = new CodeDocumentation { DescriptionTemplate = "Some documentation" } }; cls.AddProperty(new CodeProperty { Name = "message", Type = new CodeType { Name = "str" }, IsPrimaryErrorMessage = true }); property.Type.Name = "str"; diff --git a/tests/Kiota.Builder.Tests/Writers/Ruby/CodeMethodWriterTests.cs b/tests/Kiota.Builder.Tests/Writers/Ruby/CodeMethodWriterTests.cs index 6fbd418e75..abd965b639 100644 --- a/tests/Kiota.Builder.Tests/Writers/Ruby/CodeMethodWriterTests.cs +++ b/tests/Kiota.Builder.Tests/Writers/Ruby/CodeMethodWriterTests.cs @@ -704,13 +704,13 @@ public void WritesTranslatedTypesDeSerializerBody() public void WritesMethodSyncDescription() { setup(); - method.Documentation.Description = MethodDescription; + method.Documentation.DescriptionTemplate = MethodDescription; method.IsAsync = false; var parameter = new CodeParameter { Documentation = new() { - Description = ParamDescription, + DescriptionTemplate = ParamDescription, }, Name = ParamName, Type = new CodeType diff --git a/tests/Kiota.Builder.Tests/Writers/TypeScript/CodeConstantWriterTests.cs b/tests/Kiota.Builder.Tests/Writers/TypeScript/CodeConstantWriterTests.cs index 918f4ca128..fec43b8a97 100644 --- a/tests/Kiota.Builder.Tests/Writers/TypeScript/CodeConstantWriterTests.cs +++ b/tests/Kiota.Builder.Tests/Writers/TypeScript/CodeConstantWriterTests.cs @@ -87,14 +87,14 @@ public void WritesEnumOptionDescription() { Documentation = new() { - Description = "Some option description", + DescriptionTemplate = "Some option description", }, Name = "option1", }; currentEnum.AddOption(option); codeConstantWriter.WriteCodeElement(currentEnum.CodeEnumObject, writer); var result = tw.ToString(); - Assert.Contains($"/** {option.Documentation.Description} */", result); + Assert.Contains($"/** {option.Documentation.DescriptionTemplate} */", result); AssertExtensions.CurlyBracesAreClosed(result, 0); } diff --git a/tests/Kiota.Builder.Tests/Writers/TypeScript/CodeFunctionWriterTests.cs b/tests/Kiota.Builder.Tests/Writers/TypeScript/CodeFunctionWriterTests.cs index 7c8fcc2960..a3bbd00f73 100644 --- a/tests/Kiota.Builder.Tests/Writers/TypeScript/CodeFunctionWriterTests.cs +++ b/tests/Kiota.Builder.Tests/Writers/TypeScript/CodeFunctionWriterTests.cs @@ -692,12 +692,12 @@ public void WritesMethodAsyncDescription() var method = TestHelper.CreateMethod(parentClass, MethodName, ReturnTypeName); method.Kind = CodeMethodKind.Factory; method.IsStatic = true; - method.Documentation.Description = MethodDescription; + method.Documentation.DescriptionTemplate = MethodDescription; var parameter = new CodeParameter { Documentation = new() { - Description = ParamDescription, + DescriptionTemplate = ParamDescription, }, Name = ParamName, Type = new CodeType @@ -731,13 +731,13 @@ public void WritesMethodSyncDescription() var method = TestHelper.CreateMethod(parentClass, MethodName, ReturnTypeName); method.Kind = CodeMethodKind.Factory; method.IsStatic = true; - method.Documentation.Description = MethodDescription; + method.Documentation.DescriptionTemplate = MethodDescription; method.IsAsync = false; var parameter = new CodeParameter { Documentation = new() { - Description = ParamDescription, + DescriptionTemplate = ParamDescription, }, Name = ParamName, Type = new CodeType @@ -764,7 +764,7 @@ public void WritesMethodDescriptionLink() var method = TestHelper.CreateMethod(parentClass, MethodName, ReturnTypeName); method.Kind = CodeMethodKind.Factory; method.IsStatic = true; - method.Documentation.Description = MethodDescription; + method.Documentation.DescriptionTemplate = MethodDescription; method.Documentation.DocumentationLabel = "see more"; method.Documentation.DocumentationLink = new("https://foo.org/docs"); method.IsAsync = false; @@ -772,7 +772,7 @@ public void WritesMethodDescriptionLink() { Documentation = new() { - Description = ParamDescription, + DescriptionTemplate = ParamDescription, }, Name = ParamName, Type = new CodeType From 168ec25572b62ba75a332bd7dc8c4173dc5b8c89 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Wed, 31 Jan 2024 10:43:37 -0500 Subject: [PATCH 02/21] - adds type information to dynamic descriptions Signed-off-by: Vincent Biret --- .../CodeDOM/CodeDocumentation.cs | 18 +++++++++++- src/Kiota.Builder/KiotaBuilder.cs | 12 ++++++-- .../Refiners/CommonLanguageRefiner.cs | 29 ++++++++++++++----- src/Kiota.Builder/Refiners/PhpRefiner.cs | 12 +++++--- 4 files changed, 55 insertions(+), 16 deletions(-) diff --git a/src/Kiota.Builder/CodeDOM/CodeDocumentation.cs b/src/Kiota.Builder/CodeDOM/CodeDocumentation.cs index a1aa5e095a..f3865ef913 100644 --- a/src/Kiota.Builder/CodeDOM/CodeDocumentation.cs +++ b/src/Kiota.Builder/CodeDOM/CodeDocumentation.cs @@ -1,5 +1,7 @@ using System; +using System.Collections.Generic; using System.Collections.Concurrent; +using System.Linq; namespace Kiota.Builder.CodeDOM; @@ -8,6 +10,15 @@ namespace Kiota.Builder.CodeDOM; /// public class CodeDocumentation : ICloneable { + /// + /// Instantiates a new instance of the class. + /// + /// The references used by the description + public CodeDocumentation(Dictionary? typeReferences = null) + { + if (typeReferences is not null) + TypeReferences = new(typeReferences, StringComparer.OrdinalIgnoreCase); + } /// /// The description of the current element. /// @@ -54,7 +65,12 @@ public string GetDescription(Func typeReferenceResolver) var description = DescriptionTemplate; foreach (var (key, value) in TypeReferences) { - var resolvedValue = typeReferenceResolver(value); + var resolvedValue = value switch + { + CodeComposedTypeBase codeComposedTypeBase => string.Join(", ", codeComposedTypeBase.Types.Select(x => typeReferenceResolver(x)).Order(StringComparer.OrdinalIgnoreCase)) is string s && !string.IsNullOrEmpty(s) ? + s : typeReferenceResolver(value), + _ => typeReferenceResolver(value), + }; if (!string.IsNullOrEmpty(resolvedValue)) description = description.Replace($"{{{key}}}", resolvedValue, StringComparison.OrdinalIgnoreCase); } diff --git a/src/Kiota.Builder/KiotaBuilder.cs b/src/Kiota.Builder/KiotaBuilder.cs index a704bb096b..562e47faab 100644 --- a/src/Kiota.Builder/KiotaBuilder.cs +++ b/src/Kiota.Builder/KiotaBuilder.cs @@ -926,9 +926,15 @@ private void CreateUrlManagement(CodeClass currentClass, OpenApiUrlTreeNode curr Kind = isApiClientClass ? CodeMethodKind.ClientConstructor : CodeMethodKind.Constructor, IsAsync = false, IsStatic = false, - Documentation = new() - { - DescriptionTemplate = $"Instantiates a new {currentClass.Name.ToFirstCharacterUpperCase()} and sets the default values.", + Documentation = new(new() { + {"TypeName", new CodeType { + IsExternal = false, + TypeDefinition = currentClass, + } + } + }) + { + DescriptionTemplate = "Instantiates a new {TypeName} and sets the default values.", }, Access = AccessModifier.Public, ReturnType = new CodeType { Name = VoidType, IsExternal = true }, diff --git a/src/Kiota.Builder/Refiners/CommonLanguageRefiner.cs b/src/Kiota.Builder/Refiners/CommonLanguageRefiner.cs index bb168bb369..5df8e62b86 100644 --- a/src/Kiota.Builder/Refiners/CommonLanguageRefiner.cs +++ b/src/Kiota.Builder/Refiners/CommonLanguageRefiner.cs @@ -249,9 +249,14 @@ protected static void AddConstructorsForDefaultValues(CodeElement current, bool Name = "void" }, IsAsync = false, - Documentation = new() + Documentation = new(new() { + { "TypeName", new CodeType() { + IsExternal = false, + TypeDefinition = current, + }} + }) { - DescriptionTemplate = $"Instantiates a new {current.Name} and sets the default values.", + DescriptionTemplate = "Instantiates a new {TypeName} and sets the default values.", }, }); CrawlTree(current, x => AddConstructorsForDefaultValues(x, addIfInherited, forceAdd, classKindsToExclude)); @@ -472,7 +477,7 @@ private static CodeType ConvertComposedTypeToWrapper(CodeClass codeClass, CodeCo ArgumentNullException.ThrowIfNull(codeComposedType); CodeClass newClass; var description = - $"Composed type wrapper for classes {codeComposedType.Types.Select(static x => x.Name).Order(StringComparer.OrdinalIgnoreCase).Aggregate(static (x, y) => x + ", " + y)}"; + "Composed type wrapper for classes {TypesList}"; if (!supportsInnerClasses) { var @namespace = codeClass.GetImmediateParentOfType(); @@ -481,7 +486,9 @@ private static CodeType ConvertComposedTypeToWrapper(CodeClass codeClass, CodeCo newClass = @namespace.AddClass(new CodeClass { Name = codeComposedType.Name, - Documentation = new() + Documentation = new(new() { + { "TypesList", codeComposedType } + }) { DescriptionTemplate = description, }, @@ -493,7 +500,9 @@ private static CodeType ConvertComposedTypeToWrapper(CodeClass codeClass, CodeCo newClass = targetNamespace.AddClass(new CodeClass { Name = codeComposedType.Name, - Documentation = new() + Documentation = new(new() { + { "TypesList", codeComposedType } + }) { DescriptionTemplate = description }, @@ -513,7 +522,9 @@ private static CodeType ConvertComposedTypeToWrapper(CodeClass codeClass, CodeCo newClass = codeClass.AddInnerClass(new CodeClass { Name = codeComposedType.Name, - Documentation = new() + Documentation = new(new() { + { "TypesList", codeComposedType } + }) { DescriptionTemplate = description }, @@ -526,9 +537,11 @@ private static CodeType ConvertComposedTypeToWrapper(CodeClass codeClass, CodeCo { Name = x.Name, Type = x, - Documentation = new() + Documentation = new(new() { + { "TypeName", x } + }) { - DescriptionTemplate = $"Composed type representation for type {x.Name}" + DescriptionTemplate = "Composed type representation for type {TypeName}" }, }).ToArray()); if (codeComposedType.Types.All(static x => x.TypeDefinition is CodeClass targetClass && targetClass.IsOfKind(CodeClassKind.Model) || diff --git a/src/Kiota.Builder/Refiners/PhpRefiner.cs b/src/Kiota.Builder/Refiners/PhpRefiner.cs index 9a2df93aac..f8830ceeb0 100644 --- a/src/Kiota.Builder/Refiners/PhpRefiner.cs +++ b/src/Kiota.Builder/Refiners/PhpRefiner.cs @@ -354,9 +354,11 @@ private static void AddRequestConfigurationConstructors(CodeElement codeElement) Name = "constructor", Kind = CodeMethodKind.Constructor, IsAsync = false, - Documentation = new() + Documentation = new(new() { + { "TypeName", new CodeType { TypeDefinition = codeClass, IsExternal = false }} + }) { - DescriptionTemplate = $"Instantiates a new {codeClass.Name} and sets the default values.", + DescriptionTemplate = "Instantiates a new {TypeName} and sets the default values.", }, ReturnType = new CodeType { Name = "void" }, }; @@ -415,9 +417,11 @@ private static void AddQueryParameterFactoryMethod(CodeElement codeElement) IsStatic = true, Access = AccessModifier.Public, Kind = CodeMethodKind.Factory, - Documentation = new CodeDocumentation + Documentation = new(new() { + { "TypeName", queryParameterProperty.Type } + }) { - DescriptionTemplate = $"Instantiates a new {queryParameterProperty.Type.Name}." + DescriptionTemplate = "Instantiates a new {TypeName}." }, ReturnType = new CodeType { Name = queryParameterProperty.Type.Name, TypeDefinition = queryParameterProperty.Type, IsNullable = false } }; From db741621d7718389dd0e4bddc8904b99ef6cc700 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Wed, 31 Jan 2024 11:01:16 -0500 Subject: [PATCH 03/21] - code linting Signed-off-by: Vincent Biret --- src/Kiota.Builder/KiotaBuilder.cs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Kiota.Builder/KiotaBuilder.cs b/src/Kiota.Builder/KiotaBuilder.cs index 562e47faab..5fa95388b4 100644 --- a/src/Kiota.Builder/KiotaBuilder.cs +++ b/src/Kiota.Builder/KiotaBuilder.cs @@ -1721,7 +1721,7 @@ private CodeType CreateInheritedModelDeclaration(OpenApiUrlTreeNode currentNode, codeDeclaration = AddModelDeclarationIfDoesntExist(currentNode, currentSchema, className, shortestNamespace, codeDeclaration as CodeClass); } if (codeDeclaration is CodeClass currentClass && - string.IsNullOrEmpty(currentClass.Documentation.DescriptionTemplate) && + !currentClass.Documentation.DescriptionAvailable && string.IsNullOrEmpty(schema.AllOf.LastOrDefault()?.Description) && !string.IsNullOrEmpty(schema.Description)) currentClass.Documentation.DescriptionTemplate = schema.Description.CleanupDescription(); // the last allof entry often is not a reference and doesn't have a description. From 41d253f3f284afab3860693813561082e33e514b Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Wed, 31 Jan 2024 11:01:33 -0500 Subject: [PATCH 04/21] - adds missing references copy Signed-off-by: Vincent Biret --- src/Kiota.Builder/Refiners/CommonLanguageRefiner.cs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/Kiota.Builder/Refiners/CommonLanguageRefiner.cs b/src/Kiota.Builder/Refiners/CommonLanguageRefiner.cs index 5df8e62b86..7e142e8c48 100644 --- a/src/Kiota.Builder/Refiners/CommonLanguageRefiner.cs +++ b/src/Kiota.Builder/Refiners/CommonLanguageRefiner.cs @@ -186,7 +186,7 @@ current.Parent is CodeClass parentClass && IsAsync = false, Kind = CodeMethodKind.Getter, ReturnType = (CodeTypeBase)currentProperty.Type.Clone(), - Documentation = new() + Documentation = new(currentProperty.Documentation.TypeReferences.ToDictionary(static x => x.Key, static x => x.Value)) { DescriptionTemplate = $"Gets the {currentProperty.WireName} property value. {currentProperty.Documentation.DescriptionTemplate}", }, @@ -201,7 +201,7 @@ current.Parent is CodeClass parentClass && Access = AccessModifier.Public, IsAsync = false, Kind = CodeMethodKind.Setter, - Documentation = new() + Documentation = new(currentProperty.Documentation.TypeReferences.ToDictionary(static x => x.Key, static x => x.Value)) { DescriptionTemplate = $"Sets the {currentProperty.WireName} property value. {currentProperty.Documentation.DescriptionTemplate}", }, From fbd58b0bbab92e1aaae66b833b678a17cd1cdbb3 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Wed, 31 Jan 2024 11:01:51 -0500 Subject: [PATCH 05/21] - adds the ability to wrap the type reference with syntax Signed-off-by: Vincent Biret --- src/Kiota.Builder/CodeDOM/CodeDocumentation.cs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/Kiota.Builder/CodeDOM/CodeDocumentation.cs b/src/Kiota.Builder/CodeDOM/CodeDocumentation.cs index f3865ef913..7ddf262525 100644 --- a/src/Kiota.Builder/CodeDOM/CodeDocumentation.cs +++ b/src/Kiota.Builder/CodeDOM/CodeDocumentation.cs @@ -57,7 +57,7 @@ public object Clone() /// Keys MUST match the description template tokens or they will be ignored. /// public ConcurrentDictionary TypeReferences { get; private set; } = new(StringComparer.OrdinalIgnoreCase); - public string GetDescription(Func typeReferenceResolver) + public string GetDescription(Func typeReferenceResolver, string? typeReferencePrefix = null, string? typeReferenceSuffix = null) { ArgumentNullException.ThrowIfNull(typeReferenceResolver); if (string.IsNullOrEmpty(DescriptionTemplate)) @@ -67,9 +67,9 @@ public string GetDescription(Func typeReferenceResolver) { var resolvedValue = value switch { - CodeComposedTypeBase codeComposedTypeBase => string.Join(", ", codeComposedTypeBase.Types.Select(x => typeReferenceResolver(x)).Order(StringComparer.OrdinalIgnoreCase)) is string s && !string.IsNullOrEmpty(s) ? + CodeComposedTypeBase codeComposedTypeBase => string.Join(", ", codeComposedTypeBase.Types.Select(x => $"{typeReferencePrefix}{typeReferenceResolver(x)}{typeReferenceSuffix}").Order(StringComparer.OrdinalIgnoreCase)) is string s && !string.IsNullOrEmpty(s) ? s : typeReferenceResolver(value), - _ => typeReferenceResolver(value), + _ => $"{typeReferencePrefix}{typeReferenceResolver(value)}{typeReferenceSuffix}", }; if (!string.IsNullOrEmpty(resolvedValue)) description = description.Replace($"{{{key}}}", resolvedValue, StringComparison.OrdinalIgnoreCase); From f6d5e1c5941a66d0563ccb7f88140b3768b37ebf Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Wed, 31 Jan 2024 11:20:33 -0500 Subject: [PATCH 06/21] - code linting Signed-off-by: Vincent Biret --- src/Kiota.Builder/Writers/Go/CodeEnumWriter.cs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/Kiota.Builder/Writers/Go/CodeEnumWriter.cs b/src/Kiota.Builder/Writers/Go/CodeEnumWriter.cs index 903c4425cd..ee32882879 100644 --- a/src/Kiota.Builder/Writers/Go/CodeEnumWriter.cs +++ b/src/Kiota.Builder/Writers/Go/CodeEnumWriter.cs @@ -34,7 +34,7 @@ public override void WriteCodeElement(CodeEnum codeElement, LanguageWriter write int power = 0; foreach (var item in enumOptions) { - if (!string.IsNullOrEmpty(item.Documentation.DescriptionTemplate)) + if (item.Documentation.DescriptionAvailable) writer.WriteLine($"// {item.Documentation.DescriptionTemplate}"); if (isMultiValue) @@ -53,7 +53,7 @@ public override void WriteCodeElement(CodeEnum codeElement, LanguageWriter write WriteMultiValueFunction(codeElement, writer, isMultiValue); } - private void WriteStringFunction(CodeEnum codeElement, LanguageWriter writer, Boolean isMultiValue) + private void WriteStringFunction(CodeEnum codeElement, LanguageWriter writer, bool isMultiValue) { var typeName = codeElement.Name.ToFirstCharacterUpperCase(); var enumOptions = codeElement.Options.ToList(); From 972be8fe01415f2cfc823fa8f6270e99860ac9ac Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Wed, 31 Jan 2024 11:24:40 -0500 Subject: [PATCH 07/21] - adds templatization for deprecation information Signed-off-by: Vincent Biret --- .../CodeDOM/CodeDocumentation.cs | 29 +++++++------ .../CodeDOM/DeprecationInformation.cs | 11 ++++- .../Writers/CSharp/CSharpConventionService.cs | 2 +- .../Writers/Go/GoConventionService.cs | 2 +- .../Writers/Java/JavaConventionService.cs | 6 +-- .../Writers/Python/PythonConventionService.cs | 2 +- .../TypeScript/TypeScriptConventionService.cs | 2 +- ...nApiDeprecationExtensionExtensionsTests.cs | 42 +++++++++---------- 8 files changed, 55 insertions(+), 41 deletions(-) diff --git a/src/Kiota.Builder/CodeDOM/CodeDocumentation.cs b/src/Kiota.Builder/CodeDOM/CodeDocumentation.cs index 7ddf262525..d584cc3555 100644 --- a/src/Kiota.Builder/CodeDOM/CodeDocumentation.cs +++ b/src/Kiota.Builder/CodeDOM/CodeDocumentation.cs @@ -58,22 +58,27 @@ public object Clone() /// public ConcurrentDictionary TypeReferences { get; private set; } = new(StringComparer.OrdinalIgnoreCase); public string GetDescription(Func typeReferenceResolver, string? typeReferencePrefix = null, string? typeReferenceSuffix = null) + { + return GetDescriptionInternal(DescriptionTemplate, typeReferenceResolver, TypeReferences, typeReferencePrefix, typeReferenceSuffix); + } + internal static string GetDescriptionInternal(string descriptionTemplate, Func typeReferenceResolver, IDictionary? typeReferences = null, string? typeReferencePrefix = null, string? typeReferenceSuffix = null) { ArgumentNullException.ThrowIfNull(typeReferenceResolver); - if (string.IsNullOrEmpty(DescriptionTemplate)) + if (string.IsNullOrEmpty(descriptionTemplate)) return string.Empty; - var description = DescriptionTemplate; - foreach (var (key, value) in TypeReferences) - { - var resolvedValue = value switch + var description = descriptionTemplate; + if (typeReferences is not null) + foreach (var (key, value) in typeReferences) { - CodeComposedTypeBase codeComposedTypeBase => string.Join(", ", codeComposedTypeBase.Types.Select(x => $"{typeReferencePrefix}{typeReferenceResolver(x)}{typeReferenceSuffix}").Order(StringComparer.OrdinalIgnoreCase)) is string s && !string.IsNullOrEmpty(s) ? - s : typeReferenceResolver(value), - _ => $"{typeReferencePrefix}{typeReferenceResolver(value)}{typeReferenceSuffix}", - }; - if (!string.IsNullOrEmpty(resolvedValue)) - description = description.Replace($"{{{key}}}", resolvedValue, StringComparison.OrdinalIgnoreCase); - } + var resolvedValue = value switch + { + CodeComposedTypeBase codeComposedTypeBase => string.Join(", ", codeComposedTypeBase.Types.Select(x => $"{typeReferencePrefix}{typeReferenceResolver(x)}{typeReferenceSuffix}").Order(StringComparer.OrdinalIgnoreCase)) is string s && !string.IsNullOrEmpty(s) ? + s : typeReferenceResolver(value), + _ => $"{typeReferencePrefix}{typeReferenceResolver(value)}{typeReferenceSuffix}", + }; + if (!string.IsNullOrEmpty(resolvedValue)) + description = description.Replace($"{{{key}}}", resolvedValue, StringComparison.OrdinalIgnoreCase); + } return description; } public bool DescriptionAvailable diff --git a/src/Kiota.Builder/CodeDOM/DeprecationInformation.cs b/src/Kiota.Builder/CodeDOM/DeprecationInformation.cs index 7a06eac09e..523f7e47c3 100644 --- a/src/Kiota.Builder/CodeDOM/DeprecationInformation.cs +++ b/src/Kiota.Builder/CodeDOM/DeprecationInformation.cs @@ -1,5 +1,14 @@ using System; +using System.Collections.Generic; namespace Kiota.Builder.CodeDOM; -public record DeprecationInformation(string? Description, DateTimeOffset? Date = null, DateTimeOffset? RemovalDate = null, string? Version = "", bool IsDeprecated = true); +public record DeprecationInformation(string? DescriptionTemplate, DateTimeOffset? Date = null, DateTimeOffset? RemovalDate = null, string? Version = "", bool IsDeprecated = true, IDictionary? TypeReferences = null) +{ + public string GetDescription(Func typeReferenceResolver, string? typeReferencePrefix = null, string? typeReferenceSuffix = null) + { + if (DescriptionTemplate is null) + return string.Empty; + return CodeDocumentation.GetDescriptionInternal(DescriptionTemplate, typeReferenceResolver, TypeReferences, typeReferencePrefix, typeReferenceSuffix); + } +}; diff --git a/src/Kiota.Builder/Writers/CSharp/CSharpConventionService.cs b/src/Kiota.Builder/Writers/CSharp/CSharpConventionService.cs index 7db7e4fba0..c9a993e328 100644 --- a/src/Kiota.Builder/Writers/CSharp/CSharpConventionService.cs +++ b/src/Kiota.Builder/Writers/CSharp/CSharpConventionService.cs @@ -276,7 +276,7 @@ private static string GetDeprecationInformation(IDeprecableElement element) var versionComment = string.IsNullOrEmpty(element.Deprecation.Version) ? string.Empty : $" as of {element.Deprecation.Version}"; var dateComment = element.Deprecation.Date is null ? string.Empty : $" on {element.Deprecation.Date.Value.Date.ToString("yyyy-MM-dd", CultureInfo.InvariantCulture)}"; var removalComment = element.Deprecation.RemovalDate is null ? string.Empty : $" and will be removed {element.Deprecation.RemovalDate.Value.Date.ToString("yyyy-MM-dd", CultureInfo.InvariantCulture)}"; - return $"[Obsolete(\"{element.Deprecation.Description}{versionComment}{dateComment}{removalComment}\")]"; + return $"[Obsolete(\"{element.Deprecation.DescriptionTemplate}{versionComment}{dateComment}{removalComment}\")]"; } internal void WriteDeprecationAttribute(IDeprecableElement element, LanguageWriter writer) { diff --git a/src/Kiota.Builder/Writers/Go/GoConventionService.cs b/src/Kiota.Builder/Writers/Go/GoConventionService.cs index 559c0e5876..a7c7b073aa 100644 --- a/src/Kiota.Builder/Writers/Go/GoConventionService.cs +++ b/src/Kiota.Builder/Writers/Go/GoConventionService.cs @@ -252,6 +252,6 @@ internal void WriteDeprecation(IDeprecableElement element, LanguageWriter writer var versionComment = string.IsNullOrEmpty(element.Deprecation.Version) ? string.Empty : $" as of {element.Deprecation.Version}"; var dateComment = element.Deprecation.Date is null ? string.Empty : $" on {element.Deprecation.Date.Value.Date.ToString("yyyy-MM-dd", CultureInfo.InvariantCulture)}"; var removalComment = element.Deprecation.RemovalDate is null ? string.Empty : $" and will be removed {element.Deprecation.RemovalDate.Value.Date.ToString("yyyy-MM-dd", CultureInfo.InvariantCulture)}"; - WriteShortDescription($"Deprecated: {element.Deprecation.Description}{versionComment}{dateComment}{removalComment}", writer); + WriteShortDescription($"Deprecated: {element.Deprecation.DescriptionTemplate}{versionComment}{dateComment}{removalComment}", writer); } } diff --git a/src/Kiota.Builder/Writers/Java/JavaConventionService.cs b/src/Kiota.Builder/Writers/Java/JavaConventionService.cs index fd0f8367b6..fb387de49a 100644 --- a/src/Kiota.Builder/Writers/Java/JavaConventionService.cs +++ b/src/Kiota.Builder/Writers/Java/JavaConventionService.cs @@ -160,10 +160,10 @@ private string[] GetDeprecationInformationForDocumentationComment(IDeprecableEle var versionComment = string.IsNullOrEmpty(element.Deprecation.Version) ? string.Empty : $" as of {element.Deprecation.Version}"; var dateComment = element.Deprecation.Date is null ? string.Empty : $" on {element.Deprecation.Date.Value.Date.ToString("yyyy-MM-dd", CultureInfo.InvariantCulture)}"; var removalComment = element.Deprecation.RemovalDate is null ? string.Empty : $" and will be removed {element.Deprecation.RemovalDate.Value.Date.ToString("yyyy-MM-dd", CultureInfo.InvariantCulture)}"; - return new string[] { + return [ $"@deprecated", - $"{element.Deprecation.Description}{versionComment}{dateComment}{removalComment}" - }; + $"{element.Deprecation.DescriptionTemplate}{versionComment}{dateComment}{removalComment}" + ]; } internal void WriteDeprecatedAnnotation(CodeElement element, LanguageWriter writer) { diff --git a/src/Kiota.Builder/Writers/Python/PythonConventionService.cs b/src/Kiota.Builder/Writers/Python/PythonConventionService.cs index 15776a3bfd..cb887fcad1 100644 --- a/src/Kiota.Builder/Writers/Python/PythonConventionService.cs +++ b/src/Kiota.Builder/Writers/Python/PythonConventionService.cs @@ -201,7 +201,7 @@ private static string GetDeprecationInformation(IDeprecableElement element) var versionComment = string.IsNullOrEmpty(element.Deprecation.Version) ? string.Empty : $" as of {element.Deprecation.Version}"; var dateComment = element.Deprecation.Date is null ? string.Empty : $" on {element.Deprecation.Date.Value.Date.ToString("yyyy-MM-dd", CultureInfo.InvariantCulture)}"; var removalComment = element.Deprecation.RemovalDate is null ? string.Empty : $" and will be removed {element.Deprecation.RemovalDate.Value.Date.ToString("yyyy-MM-dd", CultureInfo.InvariantCulture)}"; - return $"{element.Deprecation.Description}{versionComment}{dateComment}{removalComment}"; + return $"{element.Deprecation.DescriptionTemplate}{versionComment}{dateComment}{removalComment}"; } internal void WriteDeprecationWarning(IDeprecableElement element, LanguageWriter writer) { diff --git a/src/Kiota.Builder/Writers/TypeScript/TypeScriptConventionService.cs b/src/Kiota.Builder/Writers/TypeScript/TypeScriptConventionService.cs index 78b6b61ef1..d724c79795 100644 --- a/src/Kiota.Builder/Writers/TypeScript/TypeScriptConventionService.cs +++ b/src/Kiota.Builder/Writers/TypeScript/TypeScriptConventionService.cs @@ -169,6 +169,6 @@ private string GetDeprecationComment(IDeprecableElement element) var versionComment = string.IsNullOrEmpty(element.Deprecation.Version) ? string.Empty : $" as of {element.Deprecation.Version}"; var dateComment = element.Deprecation.Date is null ? string.Empty : $" on {element.Deprecation.Date.Value.Date.ToString("yyyy-MM-dd", CultureInfo.InvariantCulture)}"; var removalComment = element.Deprecation.RemovalDate is null ? string.Empty : $" and will be removed {element.Deprecation.RemovalDate.Value.Date.ToString("yyyy-MM-dd", CultureInfo.InvariantCulture)}"; - return $"@deprecated {element.Deprecation.Description}{versionComment}{dateComment}{removalComment}"; + return $"@deprecated {element.Deprecation.DescriptionTemplate}{versionComment}{dateComment}{removalComment}"; } } diff --git a/tests/Kiota.Builder.Tests/Extensions/OpenApiDeprecationExtensionExtensionsTests.cs b/tests/Kiota.Builder.Tests/Extensions/OpenApiDeprecationExtensionExtensionsTests.cs index d4e8a7d746..10de8508c1 100644 --- a/tests/Kiota.Builder.Tests/Extensions/OpenApiDeprecationExtensionExtensionsTests.cs +++ b/tests/Kiota.Builder.Tests/Extensions/OpenApiDeprecationExtensionExtensionsTests.cs @@ -23,7 +23,7 @@ public void ToDeprecationInformation() Date = new DateTimeOffset(2021, 05, 04, 0, 0, 0, TimeSpan.Zero), }; var deprecationInformation = openApiExtension.ToDeprecationInformation(); - Assert.Equal(openApiExtension.Description, deprecationInformation.Description); + Assert.Equal(openApiExtension.Description, deprecationInformation.DescriptionTemplate); Assert.Equal(openApiExtension.Version, deprecationInformation.Version); Assert.Equal(openApiExtension.RemovalDate.Value.Year, deprecationInformation.RemovalDate.Value.Year); Assert.Equal(openApiExtension.Date.Value.Month, deprecationInformation.Date.Value.Month); @@ -47,7 +47,7 @@ public void GetsDeprecationInformationFromOpenApiSchema() var deprecationInformation = openApiSchema.GetDeprecationInformation(); Assert.NotNull(deprecationInformation); Assert.True(deprecationInformation.IsDeprecated); - Assert.Equal("description", deprecationInformation.Description); + Assert.Equal("description", deprecationInformation.DescriptionTemplate); } [Fact] public void GetsEmptyDeprecationInformationFromSchema() @@ -59,7 +59,7 @@ public void GetsEmptyDeprecationInformationFromSchema() var deprecationInformation = openApiSchema.GetDeprecationInformation(); Assert.NotNull(deprecationInformation); Assert.True(deprecationInformation.IsDeprecated); - Assert.Null(deprecationInformation.Description); + Assert.Null(deprecationInformation.DescriptionTemplate); } [Fact] public void GetsNoDeprecationInformationFromNonDeprecatedSchema() @@ -80,7 +80,7 @@ public void GetsNoDeprecationInformationFromNonDeprecatedSchema() var deprecationInformation = openApiSchema.GetDeprecationInformation(); Assert.NotNull(deprecationInformation); Assert.False(deprecationInformation.IsDeprecated); - Assert.Null(deprecationInformation.Description); + Assert.Null(deprecationInformation.DescriptionTemplate); } [Fact] public void GetsDeprecationOnOperationDirect() @@ -101,7 +101,7 @@ public void GetsDeprecationOnOperationDirect() var deprecationInformation = operation.GetDeprecationInformation(); Assert.NotNull(deprecationInformation); Assert.True(deprecationInformation.IsDeprecated); - Assert.Equal("description", deprecationInformation.Description); + Assert.Equal("description", deprecationInformation.DescriptionTemplate); } [Fact] public void GetsNoDeprecationOnNonDeprecatedOperation() @@ -122,7 +122,7 @@ public void GetsNoDeprecationOnNonDeprecatedOperation() var deprecationInformation = operation.GetDeprecationInformation(); Assert.NotNull(deprecationInformation); Assert.False(deprecationInformation.IsDeprecated); - Assert.Null(deprecationInformation.Description); + Assert.Null(deprecationInformation.DescriptionTemplate); } [Fact] public void GetsDeprecationOnOperationWithNullResponseContentTypeInstance() @@ -147,7 +147,7 @@ public void GetsDeprecationOnOperationWithNullResponseContentTypeInstance() var deprecationInformation = operation.GetDeprecationInformation(); Assert.NotNull(deprecationInformation); Assert.False(deprecationInformation.IsDeprecated); - Assert.Null(deprecationInformation.Description); + Assert.Null(deprecationInformation.DescriptionTemplate); } [Fact] public void GetsDeprecationOnOperationWithDeprecatedInlineResponseSchema() @@ -187,7 +187,7 @@ public void GetsDeprecationOnOperationWithDeprecatedInlineResponseSchema() var deprecationInformation = operation.GetDeprecationInformation(); Assert.NotNull(deprecationInformation); Assert.True(deprecationInformation.IsDeprecated); - Assert.Equal("description", deprecationInformation.Description); + Assert.Equal("description", deprecationInformation.DescriptionTemplate); } [Fact] public void GetsNoDeprecationOnOperationWithDeprecatedReferenceResponseSchema() @@ -232,7 +232,7 @@ public void GetsNoDeprecationOnOperationWithDeprecatedReferenceResponseSchema() var deprecationInformation = operation.GetDeprecationInformation(); Assert.NotNull(deprecationInformation); Assert.False(deprecationInformation.IsDeprecated); - Assert.Null(deprecationInformation.Description); + Assert.Null(deprecationInformation.DescriptionTemplate); } [Fact] public void GetsDeprecationOnOperationWithDeprecatedInlineRequestSchema() @@ -267,7 +267,7 @@ public void GetsDeprecationOnOperationWithDeprecatedInlineRequestSchema() var deprecationInformation = operation.GetDeprecationInformation(); Assert.NotNull(deprecationInformation); Assert.True(deprecationInformation.IsDeprecated); - Assert.Equal("description", deprecationInformation.Description); + Assert.Equal("description", deprecationInformation.DescriptionTemplate); } [Fact] public void GetsDeprecationOnOperationWithNullRequestBodyContentTypeInstance() @@ -287,7 +287,7 @@ public void GetsDeprecationOnOperationWithNullRequestBodyContentTypeInstance() var deprecationInformation = operation.GetDeprecationInformation(); Assert.NotNull(deprecationInformation); Assert.False(deprecationInformation.IsDeprecated); - Assert.Null(deprecationInformation.Description); + Assert.Null(deprecationInformation.DescriptionTemplate); } [Fact] public void GetsNoDeprecationOnOperationWithDeprecatedReferenceRequestSchema() @@ -327,7 +327,7 @@ public void GetsNoDeprecationOnOperationWithDeprecatedReferenceRequestSchema() var deprecationInformation = operation.GetDeprecationInformation(); Assert.NotNull(deprecationInformation); Assert.False(deprecationInformation.IsDeprecated); - Assert.Null(deprecationInformation.Description); + Assert.Null(deprecationInformation.DescriptionTemplate); } [Fact] public void GetsDeprecationInformationOnParameter() @@ -348,7 +348,7 @@ public void GetsDeprecationInformationOnParameter() var deprecationInformation = parameter.GetDeprecationInformation(); Assert.NotNull(deprecationInformation); Assert.True(deprecationInformation.IsDeprecated); - Assert.Equal("description", deprecationInformation.Description); + Assert.Equal("description", deprecationInformation.DescriptionTemplate); } [Fact] public void GetsNoDeprecationInformationOnNonDeprecatedParameter() @@ -369,7 +369,7 @@ public void GetsNoDeprecationInformationOnNonDeprecatedParameter() var deprecationInformation = parameter.GetDeprecationInformation(); Assert.NotNull(deprecationInformation); Assert.False(deprecationInformation.IsDeprecated); - Assert.Null(deprecationInformation.Description); + Assert.Null(deprecationInformation.DescriptionTemplate); } [Fact] public void GetsDeprecationInformationOnParameterWithDeprecatedInlineSchema() @@ -394,7 +394,7 @@ public void GetsDeprecationInformationOnParameterWithDeprecatedInlineSchema() var deprecationInformation = parameter.GetDeprecationInformation(); Assert.NotNull(deprecationInformation); Assert.True(deprecationInformation.IsDeprecated); - Assert.Equal("description", deprecationInformation.Description); + Assert.Equal("description", deprecationInformation.DescriptionTemplate); } [Fact] public void GetsNoDeprecationInformationOnParameterWithDeprecatedReferenceSchema() @@ -424,7 +424,7 @@ public void GetsNoDeprecationInformationOnParameterWithDeprecatedReferenceSchema var deprecationInformation = parameter.GetDeprecationInformation(); Assert.NotNull(deprecationInformation); Assert.False(deprecationInformation.IsDeprecated); - Assert.Null(deprecationInformation.Description); + Assert.Null(deprecationInformation.DescriptionTemplate); } [Fact] public void GetsDeprecationInformationOnParameterWithDeprecatedInlineContentSchema() @@ -455,7 +455,7 @@ public void GetsDeprecationInformationOnParameterWithDeprecatedInlineContentSche var deprecationInformation = parameter.GetDeprecationInformation(); Assert.NotNull(deprecationInformation); Assert.True(deprecationInformation.IsDeprecated); - Assert.Equal("description", deprecationInformation.Description); + Assert.Equal("description", deprecationInformation.DescriptionTemplate); } [Fact] public void GetsNoDeprecationInformationOnParameterWithDeprecatedReferenceContentSchema() @@ -491,7 +491,7 @@ public void GetsNoDeprecationInformationOnParameterWithDeprecatedReferenceConten var deprecationInformation = parameter.GetDeprecationInformation(); Assert.NotNull(deprecationInformation); Assert.False(deprecationInformation.IsDeprecated); - Assert.Null(deprecationInformation.Description); + Assert.Null(deprecationInformation.DescriptionTemplate); } [Fact] public void GetsDeprecationInformationFromTreeNodeWhenAllOperationsDeprecated() @@ -518,7 +518,7 @@ public void GetsDeprecationInformationFromTreeNodeWhenAllOperationsDeprecated() var deprecationInformation = treeNode.GetDeprecationInformation(); Assert.NotNull(deprecationInformation); Assert.True(deprecationInformation.IsDeprecated); - Assert.Equal("description", deprecationInformation.Description); + Assert.Equal("description", deprecationInformation.DescriptionTemplate); } [Fact] public void GetsNoDeprecationInformationFromTreeNodeOnNoOperation() @@ -533,7 +533,7 @@ public void GetsNoDeprecationInformationFromTreeNodeOnNoOperation() var deprecationInformation = treeNode.GetDeprecationInformation(); Assert.NotNull(deprecationInformation); Assert.False(deprecationInformation.IsDeprecated); - Assert.Null(deprecationInformation.Description); + Assert.Null(deprecationInformation.DescriptionTemplate); } [Fact] public void GetsNoDeprecationInformationFromTreeNodeWhenOneOperationNonDeprecated() @@ -563,6 +563,6 @@ public void GetsNoDeprecationInformationFromTreeNodeWhenOneOperationNonDeprecate var deprecationInformation = treeNode.GetDeprecationInformation(); Assert.NotNull(deprecationInformation); Assert.False(deprecationInformation.IsDeprecated); - Assert.Null(deprecationInformation.Description); + Assert.Null(deprecationInformation.DescriptionTemplate); } } From 44e97b8c5d0443e1f5c0483b07ca4c7c336e5c9f Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Wed, 31 Jan 2024 12:16:27 -0500 Subject: [PATCH 08/21] - adds type references to deprecation information Signed-off-by: Vincent Biret --- src/Kiota.Builder/CodeDOM/DeprecationInformation.cs | 2 +- src/Kiota.Builder/KiotaBuilder.cs | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/src/Kiota.Builder/CodeDOM/DeprecationInformation.cs b/src/Kiota.Builder/CodeDOM/DeprecationInformation.cs index 523f7e47c3..08ef9cc452 100644 --- a/src/Kiota.Builder/CodeDOM/DeprecationInformation.cs +++ b/src/Kiota.Builder/CodeDOM/DeprecationInformation.cs @@ -3,7 +3,7 @@ namespace Kiota.Builder.CodeDOM; -public record DeprecationInformation(string? DescriptionTemplate, DateTimeOffset? Date = null, DateTimeOffset? RemovalDate = null, string? Version = "", bool IsDeprecated = true, IDictionary? TypeReferences = null) +public record DeprecationInformation(string? DescriptionTemplate, DateTimeOffset? Date = null, DateTimeOffset? RemovalDate = null, string? Version = "", bool IsDeprecated = true, Dictionary? TypeReferences = null) { public string GetDescription(Func typeReferenceResolver, string? typeReferencePrefix = null, string? typeReferenceSuffix = null) { diff --git a/src/Kiota.Builder/KiotaBuilder.cs b/src/Kiota.Builder/KiotaBuilder.cs index 5fa95388b4..c381bdd15d 100644 --- a/src/Kiota.Builder/KiotaBuilder.cs +++ b/src/Kiota.Builder/KiotaBuilder.cs @@ -1334,7 +1334,7 @@ private void AddErrorMappingToExecutorMethod(OpenApiUrlTreeNode currentNode, Ope { Kind = CodeClassKind.Model, Name = obsoleteTypeName, - Deprecation = new($"This class is obsolete. Use {modelType.Name} instead.", IsDeprecated: true), + Deprecation = new("This class is obsolete. Use {TypeName} instead.", IsDeprecated: true, TypeReferences: new() { { "TypeName", codeType } }), Documentation = (CodeDocumentation)codeClass.Documentation.Clone() }; var originalFactoryMethod = codeClass.Methods.First(static x => x.Kind is CodeMethodKind.Factory); @@ -1362,7 +1362,7 @@ private void AddErrorMappingToExecutorMethod(OpenApiUrlTreeNode currentNode, Ope _ => throw new InvalidOperationException("Could not create an obsolete composed type"), }; obsoleteComposedType.Name = obsoleteTypeName; - obsoleteComposedType.Deprecation = new($"This class is obsolete. Use {modelType.Name} instead.", IsDeprecated: true); + obsoleteComposedType.Deprecation = new("This class is obsolete. Use {TypeName} instead.", IsDeprecated: true, TypeReferences: new() { { "TypeName", modelType } }); return (modelType, obsoleteComposedType); } } @@ -1463,7 +1463,7 @@ private void CreateOperationMethods(OpenApiUrlTreeNode currentNode, OperationTyp additionalExecutorMethod.ReturnType = returnTypes.Item2; additionalExecutorMethod.OriginalMethod = executorMethod; var newName = $"{executorMethod.Name}As{executorMethod.ReturnType.Name.ToFirstCharacterUpperCase()}"; - additionalExecutorMethod.Deprecation = new($"This method is obsolete. Use {newName} instead.", IsDeprecated: true); + additionalExecutorMethod.Deprecation = new("This method is obsolete. Use {TypeName} instead.", IsDeprecated: true, TypeReferences: new() { { "TypeName", new CodeType { TypeDefinition = executorMethod, IsExternal = false } } }); parentClass.RenameChildElement(executorMethod.Name, newName); parentClass.AddMethod(additionalExecutorMethod); } @@ -2463,7 +2463,7 @@ private void AddPropertyForQueryParameter(OpenApiUrlTreeNode node, OperationType var modernProp = (CodeProperty)prop.Clone(); modernProp.Name = $"{prop.Name}As{modernProp.Type.Name.ToFirstCharacterUpperCase()}"; modernProp.SerializationName = prop.WireName; - prop.Deprecation = new($"This property is deprecated, use {modernProp.Name} instead", IsDeprecated: true); + prop.Deprecation = new("This property is deprecated, use {TypeName} instead", IsDeprecated: true, TypeReferences: new() { { "TypeName", new CodeType { TypeDefinition = modernProp, IsExternal = false } } }); prop.Type = GetDefaultQueryParameterType(); prop.Type.CollectionKind = modernProp.Type.CollectionKind; parameterClass.AddProperty(modernProp, prop); From 2b78e231e4bcbbad95157685d279f75c1f17b3f5 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Wed, 31 Jan 2024 15:56:07 -0500 Subject: [PATCH 09/21] - switches to the type name replacement infrastructure for documentation Signed-off-by: Vincent Biret --- .../CodeDOM/CodeDocumentation.cs | 8 ++-- .../Writers/CLI/CliCodeMethodWriter.cs | 2 +- .../Writers/CSharp/CSharpConventionService.cs | 22 +++++++--- .../CSharp/CodeClassDeclarationWriter.cs | 2 +- .../Writers/CSharp/CodeEnumWriter.cs | 4 +- .../Writers/CSharp/CodeIndexerWriter.cs | 4 +- .../Writers/CSharp/CodeMethodWriter.cs | 4 +- .../Writers/CSharp/CodePropertyWriter.cs | 2 +- .../CommonLanguageConventionService.cs | 2 +- .../Writers/Go/CodeClassDeclarationWriter.cs | 2 +- .../Writers/Go/CodeEnumWriter.cs | 2 +- .../Go/CodeInterfaceDeclarationWriter.cs | 2 +- .../Writers/Go/CodeMethodWriter.cs | 3 +- .../Writers/Go/CodePropertyWriter.cs | 2 +- .../Writers/Go/GoConventionService.cs | 24 ++++++++--- .../Writers/ILanguageConventionService.cs | 2 +- .../Writers/Java/CodeEnumWriter.cs | 2 +- .../Writers/Java/CodeMethodWriter.cs | 5 ++- .../Writers/Java/JavaConventionService.cs | 21 +++++++--- .../Writers/Php/CodeClassDeclarationWriter.cs | 2 +- .../Writers/Php/CodeMethodWriter.cs | 14 +++---- .../Writers/Php/CodePropertyWriter.cs | 4 +- .../Writers/Php/PhpConventionService.cs | 41 ++++++++++-------- .../Python/CodeClassDeclarationWriter.cs | 2 +- .../Writers/Python/CodeEnumWriter.cs | 2 +- .../Writers/Python/CodeMethodWriter.cs | 12 +++--- .../Writers/Python/CodePropertyWriter.cs | 6 +-- .../Writers/Python/PythonConventionService.cs | 42 +++++++++++-------- .../Ruby/CodeClassDeclarationWriter.cs | 2 +- .../Writers/Ruby/CodeEnumWriter.cs | 4 +- .../Writers/Ruby/CodeMethodWriter.cs | 17 +++++--- .../Writers/Ruby/CodePropertyWriter.cs | 2 +- .../Writers/Ruby/RubyConventionService.cs | 14 ++++--- .../Swift/CodeClassDeclarationWriter.cs | 2 +- .../Writers/Swift/SwiftConventionService.cs | 10 +++-- .../Writers/TypeScript/CodeConstantWriter.cs | 2 +- .../Writers/TypeScript/CodeMethodWriter.cs | 4 +- .../TypeScript/TypeScriptConventionService.cs | 21 +++++++--- 38 files changed, 193 insertions(+), 125 deletions(-) diff --git a/src/Kiota.Builder/CodeDOM/CodeDocumentation.cs b/src/Kiota.Builder/CodeDOM/CodeDocumentation.cs index d584cc3555..2d8035fb76 100644 --- a/src/Kiota.Builder/CodeDOM/CodeDocumentation.cs +++ b/src/Kiota.Builder/CodeDOM/CodeDocumentation.cs @@ -57,16 +57,16 @@ public object Clone() /// Keys MUST match the description template tokens or they will be ignored. /// public ConcurrentDictionary TypeReferences { get; private set; } = new(StringComparer.OrdinalIgnoreCase); - public string GetDescription(Func typeReferenceResolver, string? typeReferencePrefix = null, string? typeReferenceSuffix = null) + public string GetDescription(Func typeReferenceResolver, string? typeReferencePrefix = null, string? typeReferenceSuffix = null, Func? normalizationFunc = null) { - return GetDescriptionInternal(DescriptionTemplate, typeReferenceResolver, TypeReferences, typeReferencePrefix, typeReferenceSuffix); + return GetDescriptionInternal(DescriptionTemplate, typeReferenceResolver, TypeReferences, typeReferencePrefix, typeReferenceSuffix, normalizationFunc); } - internal static string GetDescriptionInternal(string descriptionTemplate, Func typeReferenceResolver, IDictionary? typeReferences = null, string? typeReferencePrefix = null, string? typeReferenceSuffix = null) + internal static string GetDescriptionInternal(string descriptionTemplate, Func typeReferenceResolver, IDictionary? typeReferences = null, string? typeReferencePrefix = null, string? typeReferenceSuffix = null, Func? normalizationFunc = null) { ArgumentNullException.ThrowIfNull(typeReferenceResolver); if (string.IsNullOrEmpty(descriptionTemplate)) return string.Empty; - var description = descriptionTemplate; + var description = normalizationFunc is null ? descriptionTemplate : normalizationFunc(descriptionTemplate); if (typeReferences is not null) foreach (var (key, value) in typeReferences) { diff --git a/src/Kiota.Builder/Writers/CLI/CliCodeMethodWriter.cs b/src/Kiota.Builder/Writers/CLI/CliCodeMethodWriter.cs index 2f68db8c62..eac0cb25b8 100644 --- a/src/Kiota.Builder/Writers/CLI/CliCodeMethodWriter.cs +++ b/src/Kiota.Builder/Writers/CLI/CliCodeMethodWriter.cs @@ -476,7 +476,7 @@ private static void WriteCommandDescription(CodeMethod codeElement, LanguageWrit var builder = new StringBuilder(); if (documentation.DescriptionAvailable) { - builder.Append(documentation.DescriptionTemplate); + builder.Append(documentation.GetDescription(static type => type.Name)); } // Add content type values to description. diff --git a/src/Kiota.Builder/Writers/CSharp/CSharpConventionService.cs b/src/Kiota.Builder/Writers/CSharp/CSharpConventionService.cs index c9a993e328..7cd4558bed 100644 --- a/src/Kiota.Builder/Writers/CSharp/CSharpConventionService.cs +++ b/src/Kiota.Builder/Writers/CSharp/CSharpConventionService.cs @@ -36,21 +36,31 @@ public static void WriteNullableClosing(LanguageWriter writer) ArgumentNullException.ThrowIfNull(writer); writer.WriteLine("#endif", false); } - public override void WriteShortDescription(string description, LanguageWriter writer) + private const string ReferenceTypePrefix = ""; + public override void WriteShortDescription(IDocumentedElement element, LanguageWriter writer, string prefix = "", string suffix = "") { ArgumentNullException.ThrowIfNull(writer); - if (!string.IsNullOrEmpty(description)) - writer.WriteLine($"{DocCommentPrefix}{description.CleanupXMLString()}"); + ArgumentNullException.ThrowIfNull(element); + if (element is not CodeElement codeElement) return; + if (!element.Documentation.DescriptionAvailable) return; + var description = element.Documentation.GetDescription(type => GetTypeString(type, codeElement), ReferenceTypePrefix, ReferenceTypeSuffix, static x => x.CleanupXMLString()); + writer.WriteLine($"{DocCommentPrefix}{prefix}{description}{suffix}"); } - public void WriteLongDescription(CodeDocumentation documentation, LanguageWriter writer) + public void WriteLongDescription(IDocumentedElement element, LanguageWriter writer) { ArgumentNullException.ThrowIfNull(writer); - if (documentation is null) return; + ArgumentNullException.ThrowIfNull(element); + if (element.Documentation is not { } documentation) return; + if (element is not CodeElement codeElement) return; if (documentation.DescriptionAvailable || documentation.ExternalDocumentationAvailable) { writer.WriteLine($"{DocCommentPrefix}"); if (documentation.DescriptionAvailable) - writer.WriteLine($"{DocCommentPrefix}{documentation.DescriptionTemplate.CleanupXMLString()}"); + { + var description = element.Documentation.GetDescription(type => GetTypeString(type, codeElement), ReferenceTypePrefix, ReferenceTypeSuffix, static x => x.CleanupXMLString()); + writer.WriteLine($"{DocCommentPrefix}{description}"); + } if (documentation.ExternalDocumentationAvailable) writer.WriteLine($"{DocCommentPrefix}{documentation.DocumentationLabel} "); writer.WriteLine($"{DocCommentPrefix}"); diff --git a/src/Kiota.Builder/Writers/CSharp/CodeClassDeclarationWriter.cs b/src/Kiota.Builder/Writers/CSharp/CodeClassDeclarationWriter.cs index cf1c4d97da..fbd487b882 100644 --- a/src/Kiota.Builder/Writers/CSharp/CodeClassDeclarationWriter.cs +++ b/src/Kiota.Builder/Writers/CSharp/CodeClassDeclarationWriter.cs @@ -35,7 +35,7 @@ public override void WriteCodeElement(ClassDeclaration codeElement, LanguageWrit .Select(static x => x.ToFirstCharacterUpperCase()) .ToArray(); var derivation = derivedTypes.Length != 0 ? ": " + derivedTypes.Aggregate(static (x, y) => $"{x}, {y}") + " " : string.Empty; - conventions.WriteLongDescription(parentClass.Documentation, writer); + conventions.WriteLongDescription(parentClass, writer); conventions.WriteDeprecationAttribute(parentClass, writer); writer.StartBlock($"public class {codeElement.Name.ToFirstCharacterUpperCase()} {derivation}{{"); } diff --git a/src/Kiota.Builder/Writers/CSharp/CodeEnumWriter.cs b/src/Kiota.Builder/Writers/CSharp/CodeEnumWriter.cs index 7845a9b2d4..92d58d64fa 100644 --- a/src/Kiota.Builder/Writers/CSharp/CodeEnumWriter.cs +++ b/src/Kiota.Builder/Writers/CSharp/CodeEnumWriter.cs @@ -29,7 +29,7 @@ public override void WriteCodeElement(CodeEnum codeElement, LanguageWriter write writer.WriteLine(x); writer.StartBlock($"namespace {codeNamespace.Name} {{"); } - conventions.WriteShortDescription(codeElement.Documentation.DescriptionTemplate, writer); + conventions.WriteShortDescription(codeElement, writer); if (codeElement.Flags) writer.WriteLine("[Flags]"); conventions.WriteDeprecationAttribute(codeElement, writer); @@ -37,7 +37,7 @@ public override void WriteCodeElement(CodeEnum codeElement, LanguageWriter write var idx = 0; foreach (var option in codeElement.Options) { - conventions.WriteShortDescription(option.Documentation.DescriptionTemplate, writer); + conventions.WriteShortDescription(option, writer); if (option.IsNameEscaped) { diff --git a/src/Kiota.Builder/Writers/CSharp/CodeIndexerWriter.cs b/src/Kiota.Builder/Writers/CSharp/CodeIndexerWriter.cs index a7a75bbc74..ae27c1c982 100644 --- a/src/Kiota.Builder/Writers/CSharp/CodeIndexerWriter.cs +++ b/src/Kiota.Builder/Writers/CSharp/CodeIndexerWriter.cs @@ -12,8 +12,8 @@ public override void WriteCodeElement(CodeIndexer codeElement, LanguageWriter wr ArgumentNullException.ThrowIfNull(writer); if (codeElement.Parent is not CodeClass parentClass) throw new InvalidOperationException("The parent of a property should be a class"); var returnType = conventions.GetTypeString(codeElement.ReturnType, codeElement); - conventions.WriteShortDescription(codeElement.Documentation.DescriptionTemplate, writer); - writer.WriteLine($"{conventions.DocCommentPrefix}{codeElement.IndexParameter.Documentation.DescriptionTemplate.CleanupXMLString()}"); + conventions.WriteShortDescription(codeElement, writer); + conventions.WriteShortDescription(codeElement.IndexParameter, writer, $"", ""); conventions.WriteDeprecationAttribute(codeElement, writer); writer.StartBlock($"public {returnType} this[{conventions.GetTypeString(codeElement.IndexParameter.Type, codeElement)} position] {{ get {{"); if (parentClass.GetPropertyOfKind(CodePropertyKind.PathParameters) is CodeProperty pathParametersProp) diff --git a/src/Kiota.Builder/Writers/CSharp/CodeMethodWriter.cs b/src/Kiota.Builder/Writers/CSharp/CodeMethodWriter.cs index 65c206678f..85b27d1c1b 100644 --- a/src/Kiota.Builder/Writers/CSharp/CodeMethodWriter.cs +++ b/src/Kiota.Builder/Writers/CSharp/CodeMethodWriter.cs @@ -541,11 +541,11 @@ protected string GetSendRequestMethodName(bool isVoid, CodeElement currentElemen } private void WriteMethodDocumentation(CodeMethod code, LanguageWriter writer) { - conventions.WriteLongDescription(code.Documentation, writer); + conventions.WriteLongDescription(code, writer); foreach (var paramWithDescription in code.Parameters .Where(static x => x.Documentation.DescriptionAvailable) .OrderBy(static x => x.Name, StringComparer.OrdinalIgnoreCase)) - writer.WriteLine($"{conventions.DocCommentPrefix}{paramWithDescription.Documentation.DescriptionTemplate.CleanupXMLString()}"); + conventions.WriteShortDescription(paramWithDescription, writer, $"", ""); conventions.WriteDeprecationAttribute(code, writer); } private static readonly BaseCodeParameterOrderComparer parameterOrderComparer = new(); diff --git a/src/Kiota.Builder/Writers/CSharp/CodePropertyWriter.cs b/src/Kiota.Builder/Writers/CSharp/CodePropertyWriter.cs index b2f3aa476f..e4b9efffe7 100644 --- a/src/Kiota.Builder/Writers/CSharp/CodePropertyWriter.cs +++ b/src/Kiota.Builder/Writers/CSharp/CodePropertyWriter.cs @@ -16,7 +16,7 @@ public override void WriteCodeElement(CodeProperty codeElement, LanguageWriter w && codeElement.IsOfKind( CodePropertyKind.Custom, CodePropertyKind.QueryParameter);// Other property types are appropriately constructor initialized - conventions.WriteShortDescription(codeElement.Documentation.DescriptionTemplate, writer); + conventions.WriteShortDescription(codeElement, writer); conventions.WriteDeprecationAttribute(codeElement, writer); if (isNullableReferenceType) { diff --git a/src/Kiota.Builder/Writers/CommonLanguageConventionService.cs b/src/Kiota.Builder/Writers/CommonLanguageConventionService.cs index 5845573c50..313583b196 100644 --- a/src/Kiota.Builder/Writers/CommonLanguageConventionService.cs +++ b/src/Kiota.Builder/Writers/CommonLanguageConventionService.cs @@ -41,5 +41,5 @@ public string TranslateType(CodeTypeBase type) } public abstract string TranslateType(CodeType type); - public abstract void WriteShortDescription(string description, LanguageWriter writer); + public abstract void WriteShortDescription(IDocumentedElement element, LanguageWriter writer, string prefix = "", string suffix = ""); } diff --git a/src/Kiota.Builder/Writers/Go/CodeClassDeclarationWriter.cs b/src/Kiota.Builder/Writers/Go/CodeClassDeclarationWriter.cs index e609e7c11b..b8e77e213e 100644 --- a/src/Kiota.Builder/Writers/Go/CodeClassDeclarationWriter.cs +++ b/src/Kiota.Builder/Writers/Go/CodeClassDeclarationWriter.cs @@ -15,7 +15,7 @@ protected override void WriteTypeDeclaration(ClassDeclaration codeElement, Langu ArgumentNullException.ThrowIfNull(writer); var className = codeElement.Name.ToFirstCharacterUpperCase(); if (codeElement.Parent is not CodeClass currentClass) throw new InvalidOperationException("The parent of a class declaration should be a class"); - conventions.WriteShortDescription($"{className} {currentClass.Documentation.DescriptionTemplate.ToFirstCharacterLowerCase()}", writer); + conventions.WriteShortDescription(currentClass, writer, $"A {className}"); conventions.WriteDeprecation(currentClass, writer); conventions.WriteLinkDescription(currentClass.Documentation, writer); writer.StartBlock($"type {className} struct {{"); diff --git a/src/Kiota.Builder/Writers/Go/CodeEnumWriter.cs b/src/Kiota.Builder/Writers/Go/CodeEnumWriter.cs index ee32882879..ecb596c681 100644 --- a/src/Kiota.Builder/Writers/Go/CodeEnumWriter.cs +++ b/src/Kiota.Builder/Writers/Go/CodeEnumWriter.cs @@ -22,7 +22,7 @@ public override void WriteCodeElement(CodeEnum codeElement, LanguageWriter write writer.CloseBlock(")"); var typeName = codeElement.Name.ToFirstCharacterUpperCase(); - conventions.WriteShortDescription(codeElement.Documentation.DescriptionTemplate, writer); + conventions.WriteShortDescription(codeElement, writer); conventions.WriteDeprecation(codeElement, writer); writer.WriteLines($"type {typeName} int", string.Empty, diff --git a/src/Kiota.Builder/Writers/Go/CodeInterfaceDeclarationWriter.cs b/src/Kiota.Builder/Writers/Go/CodeInterfaceDeclarationWriter.cs index 80e00c54c5..7bb0f7b09f 100644 --- a/src/Kiota.Builder/Writers/Go/CodeInterfaceDeclarationWriter.cs +++ b/src/Kiota.Builder/Writers/Go/CodeInterfaceDeclarationWriter.cs @@ -13,7 +13,7 @@ protected override void WriteTypeDeclaration(InterfaceDeclaration codeElement, L ArgumentNullException.ThrowIfNull(writer); if (codeElement.Parent is not CodeInterface inter) throw new InvalidOperationException("Expected the parent to be an interface"); var interName = codeElement.Name.ToFirstCharacterUpperCase(); - conventions.WriteShortDescription($"{interName} {inter.Documentation.DescriptionTemplate.ToFirstCharacterLowerCase()}", writer); + conventions.WriteShortDescription(inter, writer, $"A {interName}"); if (codeElement.Parent is CodeInterface currentInterface && currentInterface.OriginalClass is not null) conventions.WriteDeprecation(currentInterface.OriginalClass, writer); conventions.WriteLinkDescription(inter.Documentation, writer); diff --git a/src/Kiota.Builder/Writers/Go/CodeMethodWriter.cs b/src/Kiota.Builder/Writers/Go/CodeMethodWriter.cs index e6398723a4..ee709bed1c 100644 --- a/src/Kiota.Builder/Writers/Go/CodeMethodWriter.cs +++ b/src/Kiota.Builder/Writers/Go/CodeMethodWriter.cs @@ -290,8 +290,7 @@ private void WriteFactoryMethodBodyForUnionModelForUnDiscriminatedTypes(CodeClas private void WriteMethodDocumentation(CodeMethod code, string methodName, LanguageWriter writer) { - if (code.Documentation.DescriptionAvailable) - conventions.WriteShortDescription($"{methodName.ToFirstCharacterUpperCase()} {code.Documentation.DescriptionTemplate.ToFirstCharacterLowerCase()}", writer); + conventions.WriteShortDescription(code, writer, $"{methodName.ToFirstCharacterUpperCase()} "); conventions.WriteDeprecation(code, writer); conventions.WriteLinkDescription(code.Documentation, writer); } diff --git a/src/Kiota.Builder/Writers/Go/CodePropertyWriter.cs b/src/Kiota.Builder/Writers/Go/CodePropertyWriter.cs index 3003f1d81b..9c51628129 100644 --- a/src/Kiota.Builder/Writers/Go/CodePropertyWriter.cs +++ b/src/Kiota.Builder/Writers/Go/CodePropertyWriter.cs @@ -26,7 +26,7 @@ public override void WriteCodeElement(CodeProperty codeElement, LanguageWriter w goto default; default: var returnType = codeElement.Parent is CodeElement parent ? conventions.GetTypeString(codeElement.Type, parent) : string.Empty; - conventions.WriteShortDescription(codeElement.Documentation.DescriptionTemplate, writer); + conventions.WriteShortDescription(codeElement, writer); conventions.WriteDeprecation(codeElement, writer); writer.WriteLine($"{propertyName} {returnType}{suffix}"); break; diff --git a/src/Kiota.Builder/Writers/Go/GoConventionService.cs b/src/Kiota.Builder/Writers/Go/GoConventionService.cs index a7c7b073aa..24f08cbc05 100644 --- a/src/Kiota.Builder/Writers/Go/GoConventionService.cs +++ b/src/Kiota.Builder/Writers/Go/GoConventionService.cs @@ -166,7 +166,21 @@ currentEnumDefinition.Parent is CodeNamespace enumNS && return string.Empty; } - public override void WriteShortDescription(string description, LanguageWriter writer) + public override void WriteShortDescription(IDocumentedElement element, LanguageWriter writer, string prefix = "", string suffix = "") + { + ArgumentNullException.ThrowIfNull(writer); + ArgumentNullException.ThrowIfNull(element); + if (!element.Documentation.DescriptionAvailable) return; + if (element is not CodeElement codeElement) return; + + var description = element.Documentation.GetDescription(x => GetTypeString(x, codeElement)); + if (!string.IsNullOrEmpty(prefix)) + { + description = description.ToFirstCharacterLowerCase(); + } + WriteDescriptionItem($"{prefix}{description}{suffix}", writer); + } + public void WriteDescriptionItem(string description, LanguageWriter writer) { ArgumentNullException.ThrowIfNull(writer); writer.WriteLine($"{DocCommentPrefix}{description}"); @@ -176,9 +190,9 @@ public void WriteLinkDescription(CodeDocumentation documentation, LanguageWriter if (documentation is null) return; if (documentation.ExternalDocumentationAvailable) { - WriteShortDescription($"[{documentation.DocumentationLabel}]", writer); - WriteShortDescription(string.Empty, writer); - WriteShortDescription($"[{documentation.DocumentationLabel}]: {documentation.DocumentationLink}", writer); + WriteDescriptionItem($"[{documentation.DocumentationLabel}]", writer); + WriteDescriptionItem(string.Empty, writer); + WriteDescriptionItem($"[{documentation.DocumentationLabel}]: {documentation.DocumentationLink}", writer); } } #pragma warning disable CA1822 // Method should be static @@ -252,6 +266,6 @@ internal void WriteDeprecation(IDeprecableElement element, LanguageWriter writer var versionComment = string.IsNullOrEmpty(element.Deprecation.Version) ? string.Empty : $" as of {element.Deprecation.Version}"; var dateComment = element.Deprecation.Date is null ? string.Empty : $" on {element.Deprecation.Date.Value.Date.ToString("yyyy-MM-dd", CultureInfo.InvariantCulture)}"; var removalComment = element.Deprecation.RemovalDate is null ? string.Empty : $" and will be removed {element.Deprecation.RemovalDate.Value.Date.ToString("yyyy-MM-dd", CultureInfo.InvariantCulture)}"; - WriteShortDescription($"Deprecated: {element.Deprecation.DescriptionTemplate}{versionComment}{dateComment}{removalComment}", writer); + WriteDescriptionItem($"Deprecated: {element.Deprecation.DescriptionTemplate}{versionComment}{dateComment}{removalComment}", writer); } } diff --git a/src/Kiota.Builder/Writers/ILanguageConventionService.cs b/src/Kiota.Builder/Writers/ILanguageConventionService.cs index 30f7690a9d..8b65e9018f 100644 --- a/src/Kiota.Builder/Writers/ILanguageConventionService.cs +++ b/src/Kiota.Builder/Writers/ILanguageConventionService.cs @@ -27,5 +27,5 @@ string TempDictionaryVarName string GetTypeString(CodeTypeBase code, CodeElement targetElement, bool includeCollectionInformation = true, LanguageWriter? writer = null); string TranslateType(CodeType type); string GetParameterSignature(CodeParameter parameter, CodeElement targetElement, LanguageWriter? writer = null); - void WriteShortDescription(string description, LanguageWriter writer); + void WriteShortDescription(IDocumentedElement element, LanguageWriter writer, string prefix = "", string suffix = ""); } diff --git a/src/Kiota.Builder/Writers/Java/CodeEnumWriter.cs b/src/Kiota.Builder/Writers/Java/CodeEnumWriter.cs index 06ac05e55b..480c4be91e 100644 --- a/src/Kiota.Builder/Writers/Java/CodeEnumWriter.cs +++ b/src/Kiota.Builder/Writers/Java/CodeEnumWriter.cs @@ -27,7 +27,7 @@ public override void WriteCodeElement(CodeEnum codeElement, LanguageWriter write var lastEnumOption = enumOptions.Last(); foreach (var enumOption in enumOptions) { - conventions.WriteShortDescription(enumOption.Documentation.DescriptionTemplate, writer); + conventions.WriteShortDescription(enumOption, writer); writer.WriteLine($"{enumOption.Name}(\"{enumOption.SerializationName}\"){(enumOption == lastEnumOption ? ";" : ",")}"); } writer.WriteLines("public final String value;", diff --git a/src/Kiota.Builder/Writers/Java/CodeMethodWriter.cs b/src/Kiota.Builder/Writers/Java/CodeMethodWriter.cs index c50c36e587..639f42f6de 100644 --- a/src/Kiota.Builder/Writers/Java/CodeMethodWriter.cs +++ b/src/Kiota.Builder/Writers/Java/CodeMethodWriter.cs @@ -1,6 +1,7 @@ using System; using System.Collections.Generic; using System.Linq; +using System.Text; using System.Text.RegularExpressions; using Kiota.Builder.CodeDOM; using Kiota.Builder.Extensions; @@ -742,8 +743,8 @@ private void WriteMethodDocumentation(CodeMethod code, LanguageWriter writer, st code.Parameters .Where(static x => x.Documentation.DescriptionAvailable) .OrderBy(static x => x.Name, StringComparer.OrdinalIgnoreCase) - .Select(x => $"@param {x.Name} {JavaConventionService.RemoveInvalidDescriptionCharacters(x.Documentation.DescriptionTemplate)}") - .Union(new[] { returnRemark })); + .Select(x => $"@param {x.Name} {x.Documentation.GetDescription(y => conventions.GetTypeString(y, code), normalizationFunc: JavaConventionService.RemoveInvalidDescriptionCharacters)}") + .Union([returnRemark])); if (!returnVoid) //Nullable/Nonnull annotations for returns are a part of Method Documentation writer.WriteLine(code.ReturnType.IsNullable ? "@jakarta.annotation.Nullable" : "@jakarta.annotation.Nonnull"); } diff --git a/src/Kiota.Builder/Writers/Java/JavaConventionService.cs b/src/Kiota.Builder/Writers/Java/JavaConventionService.cs index fb387de49a..088867a10e 100644 --- a/src/Kiota.Builder/Writers/Java/JavaConventionService.cs +++ b/src/Kiota.Builder/Writers/Java/JavaConventionService.cs @@ -5,7 +5,6 @@ using System.Text.RegularExpressions; using Kiota.Builder.CodeDOM; -using Kiota.Builder.Extensions; using Kiota.Builder.Refiners; namespace Kiota.Builder.Writers.Java; @@ -93,24 +92,34 @@ _ when type.Name.Contains('.', StringComparison.OrdinalIgnoreCase) => type.Name, _ => type.Name is string typeName && !string.IsNullOrEmpty(typeName) ? typeName : "Object", }; } - public override void WriteShortDescription(string description, LanguageWriter writer) + private const string ReferenceTypePrefix = "{@link #"; + private const string ReferenceTypeSuffix = "}"; + public override void WriteShortDescription(IDocumentedElement element, LanguageWriter writer, string prefix = "", string suffix = "") { ArgumentNullException.ThrowIfNull(writer); - if (!string.IsNullOrEmpty(description)) - writer.WriteLine($"{DocCommentStart} {RemoveInvalidDescriptionCharacters(description)}{DocCommentEnd}"); + ArgumentNullException.ThrowIfNull(element); + if (!element.Documentation.DescriptionAvailable) return; + if (element is not CodeElement codeElement) return; + + var description = element.Documentation.GetDescription(x => GetTypeString(x, codeElement), ReferenceTypePrefix, ReferenceTypeSuffix, RemoveInvalidDescriptionCharacters); + + writer.WriteLine($"{DocCommentStart} {description}{DocCommentEnd}"); } public void WriteLongDescription(CodeElement element, LanguageWriter writer, IEnumerable? additionalRemarks = default) { ArgumentNullException.ThrowIfNull(writer); if (element is not IDocumentedElement documentedElement || documentedElement.Documentation is not CodeDocumentation documentation) return; if (additionalRemarks == default) - additionalRemarks = Enumerable.Empty(); + additionalRemarks = []; var remarks = additionalRemarks.ToArray(); if (documentation.DescriptionAvailable || documentation.ExternalDocumentationAvailable || remarks.Length != 0) { writer.WriteLine(DocCommentStart); if (documentation.DescriptionAvailable) - writer.WriteLine($"{DocCommentPrefix}{RemoveInvalidDescriptionCharacters(documentation.DescriptionTemplate)}"); + { + var description = documentedElement.Documentation.GetDescription(x => GetTypeString(x, element), ReferenceTypePrefix, ReferenceTypeSuffix, RemoveInvalidDescriptionCharacters); + writer.WriteLine($"{DocCommentPrefix}{description}"); + } foreach (var additionalRemark in remarks.Where(static x => !string.IsNullOrEmpty(x))) writer.WriteLine($"{DocCommentPrefix}{additionalRemark}"); if (element is IDeprecableElement deprecableElement && deprecableElement.Deprecation is not null && deprecableElement.Deprecation.IsDeprecated) diff --git a/src/Kiota.Builder/Writers/Php/CodeClassDeclarationWriter.cs b/src/Kiota.Builder/Writers/Php/CodeClassDeclarationWriter.cs index 86bfb60fc1..58ecf96480 100644 --- a/src/Kiota.Builder/Writers/Php/CodeClassDeclarationWriter.cs +++ b/src/Kiota.Builder/Writers/Php/CodeClassDeclarationWriter.cs @@ -17,7 +17,7 @@ public override void WriteCodeElement(ClassDeclaration codeElement, LanguageWrit conventions.WritePhpDocumentStart(writer); conventions.WriteNamespaceAndImports(codeElement, writer); if (codeElement.Parent is CodeClass parentClass) - conventions.WriteLongDescription(parentClass.Documentation, writer); + conventions.WriteLongDescription(parentClass, writer); var derivation = (codeElement.Inherits == null ? string.Empty : $" extends {codeElement.Inherits.Name.ToFirstCharacterUpperCase()}") + (!codeElement.Implements.Any() ? string.Empty : $" implements {codeElement.Implements.Select(x => x.Name).Aggregate((x, y) => x + ", " + y)}"); writer.WriteLine($"class {codeElement.Name.Split('.').Last().ToFirstCharacterUpperCase()}{derivation} "); diff --git a/src/Kiota.Builder/Writers/Php/CodeMethodWriter.cs b/src/Kiota.Builder/Writers/Php/CodeMethodWriter.cs index 075929d5d7..fd7151dde8 100644 --- a/src/Kiota.Builder/Writers/Php/CodeMethodWriter.cs +++ b/src/Kiota.Builder/Writers/Php/CodeMethodWriter.cs @@ -258,7 +258,7 @@ private static void AssignPropertyFromParameter(CodeClass parentClass, CodeMetho private void WriteMethodPhpDocs(CodeMethod codeMethod, LanguageWriter writer) { - var methodDescription = codeMethod.Documentation.DescriptionTemplate; + var methodDescription = codeMethod.Documentation.GetDescription(x => conventions.GetTypeString(x, codeMethod), normalizationFunc: PhpConventionService.RemoveInvalidDescriptionCharacters); var methodThrows = codeMethod.IsOfKind(CodeMethodKind.RequestExecutor); var hasMethodDescription = !string.IsNullOrEmpty(methodDescription.Trim()); if (!hasMethodDescription && !codeMethod.Parameters.Any()) @@ -274,15 +274,15 @@ private void WriteMethodPhpDocs(CodeMethod codeMethod, LanguageWriter writer) var returnDocString = GetDocCommentReturnType(codeMethod); if (!isVoidable) { - var nullableSuffix = (codeMethod.ReturnType.IsNullable ? "|null" : ""); + var nullableSuffix = codeMethod.ReturnType.IsNullable ? "|null" : ""; returnDocString = (codeMethod.Kind == CodeMethodKind.RequestExecutor) ? $"@return Promise<{returnDocString}|null>" : $"@return {returnDocString}{nullableSuffix}"; } - else returnDocString = String.Empty; + else returnDocString = string.Empty; - var throwsArray = methodThrows ? new[] { "@throws Exception" } : Array.Empty(); - conventions.WriteLongDescription(codeMethod.Documentation, + var throwsArray = methodThrows ? ["@throws Exception"] : Array.Empty(); + conventions.WriteLongDescription(codeMethod, writer, parametersWithOrWithoutDescription.Union(new[] { returnDocString }).Union(throwsArray) ); @@ -306,9 +306,9 @@ private string GetParameterDocString(CodeMethod codeMethod, CodeParameter x) if (codeMethod.IsOfKind(CodeMethodKind.Setter) && (codeMethod.AccessedProperty?.IsOfKind(CodePropertyKind.AdditionalData) ?? false)) { - return $"@param array $value {x?.Documentation.DescriptionTemplate}"; + return $"@param array $value {x?.Documentation.GetDescription(x => conventions.GetTypeString(x, codeMethod), normalizationFunc: PhpConventionService.RemoveInvalidDescriptionCharacters)}"; } - return $"@param {conventions.GetParameterDocNullable(x, x)} {x?.Documentation.DescriptionTemplate}"; + return $"@param {conventions.GetParameterDocNullable(x, x)} {x?.Documentation.GetDescription(x => conventions.GetTypeString(x, codeMethod), normalizationFunc: PhpConventionService.RemoveInvalidDescriptionCharacters)}"; } private static readonly BaseCodeParameterOrderComparer parameterOrderComparer = new(); diff --git a/src/Kiota.Builder/Writers/Php/CodePropertyWriter.cs b/src/Kiota.Builder/Writers/Php/CodePropertyWriter.cs index e29df89762..211d3e7965 100644 --- a/src/Kiota.Builder/Writers/Php/CodePropertyWriter.cs +++ b/src/Kiota.Builder/Writers/Php/CodePropertyWriter.cs @@ -32,7 +32,7 @@ public override void WriteCodeElement(CodeProperty codeElement, LanguageWriter w private void WritePropertyDocComment(CodeProperty codeProperty, LanguageWriter writer) { - var propertyDescription = codeProperty.Documentation.DescriptionTemplate; + var propertyDescription = codeProperty.Documentation.GetDescription(x => conventions.GetTypeString(x, codeProperty), normalizationFunc: PhpConventionService.RemoveInvalidDescriptionCharacters); var hasDescription = codeProperty.Documentation.DescriptionAvailable; var collectionKind = codeProperty.Type.IsArray || codeProperty.Type.IsCollection; @@ -63,7 +63,7 @@ private string GetCollectionDocString(CodeProperty codeProperty) private void WriteRequestBuilderBody(CodeProperty codeElement, LanguageWriter writer, string returnType, string propertyAccess, string propertyName) { - conventions.WriteShortDescription(codeElement.Documentation.DescriptionTemplate, writer); + conventions.WriteShortDescription(codeElement, writer); writer.WriteLine($"{propertyAccess} function {propertyName}(): {returnType} {{"); writer.IncreaseIndent(); conventions.AddRequestBuilderBody(returnType, writer); diff --git a/src/Kiota.Builder/Writers/Php/PhpConventionService.cs b/src/Kiota.Builder/Writers/Php/PhpConventionService.cs index b29e086c6b..b2f1096153 100644 --- a/src/Kiota.Builder/Writers/Php/PhpConventionService.cs +++ b/src/Kiota.Builder/Writers/Php/PhpConventionService.cs @@ -135,37 +135,44 @@ private string GetCollectionDocString(CodeParameter codeParameter) return codeParameter.Optional ? $"{doc}|null" : doc; } - private static string RemoveInvalidDescriptionCharacters(string originalDescription) => originalDescription.Replace("\\", "/", StringComparison.OrdinalIgnoreCase); - public override void WriteShortDescription(string description, LanguageWriter writer) + internal static string RemoveInvalidDescriptionCharacters(string originalDescription) => originalDescription.Replace("\\", "/", StringComparison.OrdinalIgnoreCase); + public override void WriteShortDescription(IDocumentedElement element, LanguageWriter writer, string prefix = "", string suffix = "") { ArgumentNullException.ThrowIfNull(writer); - if (!string.IsNullOrEmpty(description)) - { - writer.WriteLine(DocCommentStart); - writer.WriteLine( - $"{DocCommentPrefix}{RemoveInvalidDescriptionCharacters(description)}"); - writer.WriteLine(DocCommentEnd); - } + ArgumentNullException.ThrowIfNull(element); + if (!element.Documentation.DescriptionAvailable) return; + if (element is not CodeElement codeElement) return; + + var description = element.Documentation.GetDescription(type => GetTypeString(type, codeElement), normalizationFunc: RemoveInvalidDescriptionCharacters); + + writer.WriteLine(DocCommentStart); + writer.WriteLine($"{DocCommentPrefix}{description}"); + writer.WriteLine(DocCommentEnd); } - public void WriteLongDescription(CodeDocumentation codeDocumentation, LanguageWriter writer, IEnumerable? additionalRemarks = default) + public void WriteLongDescription(IDocumentedElement element, LanguageWriter writer, IEnumerable? additionalRemarks = default) { ArgumentNullException.ThrowIfNull(writer); - if (codeDocumentation is null) return; - additionalRemarks ??= Enumerable.Empty(); + ArgumentNullException.ThrowIfNull(element); + if (element.Documentation is not { } documentation) return; + if (element is not CodeElement codeElement) return; + additionalRemarks ??= []; var enumerableArray = additionalRemarks as string[] ?? additionalRemarks.ToArray(); - if (codeDocumentation.DescriptionAvailable || codeDocumentation.ExternalDocumentationAvailable || + if (documentation.DescriptionAvailable || documentation.ExternalDocumentationAvailable || enumerableArray.Length != 0) { writer.WriteLine(DocCommentStart); - if (codeDocumentation.DescriptionAvailable) - writer.WriteLine($"{DocCommentPrefix}{RemoveInvalidDescriptionCharacters(codeDocumentation.DescriptionTemplate)}"); + if (documentation.DescriptionAvailable) + { + var description = element.Documentation.GetDescription(type => GetTypeString(type, codeElement), normalizationFunc: RemoveInvalidDescriptionCharacters); + writer.WriteLine($"{DocCommentPrefix}{description}"); + } foreach (var additionalRemark in enumerableArray.Where(static x => !string.IsNullOrEmpty(x))) writer.WriteLine($"{DocCommentPrefix}{additionalRemark}"); - if (codeDocumentation.ExternalDocumentationAvailable) - writer.WriteLine($"{DocCommentPrefix}@link {codeDocumentation.DocumentationLink} {codeDocumentation.DocumentationLabel}"); + if (documentation.ExternalDocumentationAvailable) + writer.WriteLine($"{DocCommentPrefix}@link {documentation.DocumentationLink} {documentation.DocumentationLabel}"); writer.WriteLine(DocCommentEnd); } diff --git a/src/Kiota.Builder/Writers/Python/CodeClassDeclarationWriter.cs b/src/Kiota.Builder/Writers/Python/CodeClassDeclarationWriter.cs index adef1bf4a9..765dc76942 100644 --- a/src/Kiota.Builder/Writers/Python/CodeClassDeclarationWriter.cs +++ b/src/Kiota.Builder/Writers/Python/CodeClassDeclarationWriter.cs @@ -50,7 +50,7 @@ public override void WriteCodeElement(ClassDeclaration codeElement, LanguageWrit _codeUsingWriter.WriteExternalImports(codeElement, writer); _codeUsingWriter.WriteConditionalInternalImports(codeElement, writer, parentNamespace); } - conventions.WriteLongDescription(parent.Documentation, writer); + conventions.WriteLongDescription(parent, writer); conventions.WriteDeprecationWarning(parent, writer); } } diff --git a/src/Kiota.Builder/Writers/Python/CodeEnumWriter.cs b/src/Kiota.Builder/Writers/Python/CodeEnumWriter.cs index 2464a22049..e92e01c2f1 100644 --- a/src/Kiota.Builder/Writers/Python/CodeEnumWriter.cs +++ b/src/Kiota.Builder/Writers/Python/CodeEnumWriter.cs @@ -24,7 +24,7 @@ public override void WriteCodeElement(CodeEnum codeElement, LanguageWriter write { codeElement.Options.ToList().ForEach(x => { - conventions.WriteInLineDescription(x.Documentation.DescriptionTemplate, writer); + conventions.WriteInLineDescription(x, writer); writer.WriteLine($"{x.Name} = \"{x.WireName}\","); }); } diff --git a/src/Kiota.Builder/Writers/Python/CodeMethodWriter.cs b/src/Kiota.Builder/Writers/Python/CodeMethodWriter.cs index b57236d080..1c4f8c5814 100644 --- a/src/Kiota.Builder/Writers/Python/CodeMethodWriter.cs +++ b/src/Kiota.Builder/Writers/Python/CodeMethodWriter.cs @@ -387,7 +387,7 @@ private void WriteDirectAccessProperties(CodeClass parentClass, LanguageWriter w _codeUsingWriter.WriteDeferredImport(parentClass, enumDefinition.Name, writer); defaultValue = $"{enumDefinition.Name}({defaultValue})"; } - conventions.WriteInLineDescription(propWithDefault.Documentation.DescriptionTemplate, writer); + conventions.WriteInLineDescription(propWithDefault, writer); if (parentClass.IsOfKind(CodeClassKind.Model)) { writer.WriteLine($"{propWithDefault.Name}: {(propWithDefault.Type.IsNullable ? "Optional[" : string.Empty)}{returnType}{(propWithDefault.Type.IsNullable ? "]" : string.Empty)} = {defaultValue}"); @@ -416,7 +416,7 @@ private void WriteSetterAccessProperties(CodeClass parentClass, LanguageWriter w defaultValue = $"{enumDefinition.Name}({defaultValue})"; } var returnType = conventions.GetTypeString(propWithDefault.Type, propWithDefault, true, writer); - conventions.WriteInLineDescription(propWithDefault.Documentation.DescriptionTemplate, writer); + conventions.WriteInLineDescription(propWithDefault, writer); var setterString = $"{propWithDefault.Name}: {(propWithDefault.Type.IsNullable ? "Optional[" : string.Empty)}{returnType}{(propWithDefault.Type.IsNullable ? "]" : string.Empty)} = {defaultValue}"; if (parentClass.IsOfKind(CodeClassKind.Model)) { @@ -434,7 +434,7 @@ private void WriteSetterAccessPropertiesWithoutDefaults(CodeClass parentClass, L .ThenBy(static x => x.Name)) { var returnType = conventions.GetTypeString(propWithoutDefault.Type, propWithoutDefault, true, writer); - conventions.WriteInLineDescription(propWithoutDefault.Documentation.DescriptionTemplate, writer); + conventions.WriteInLineDescription(propWithoutDefault, writer); if (parentClass.IsOfKind(CodeClassKind.Model)) writer.WriteLine($"{propWithoutDefault.Name}: {(propWithoutDefault.Type.IsNullable ? "Optional[" : string.Empty)}{returnType}{(propWithoutDefault.Type.IsNullable ? "]" : string.Empty)} = None"); else @@ -706,13 +706,13 @@ private void WriteMethodDocumentation(CodeMethod code, LanguageWriter writer, st var nullablePrefix = code.ReturnType.IsNullable && !isVoid ? "Optional[" : string.Empty; var nullableSuffix = code.ReturnType.IsNullable && !isVoid ? "]" : string.Empty; var returnRemark = isVoid ? "Returns: None" : $"Returns: {nullablePrefix}{returnType}{nullableSuffix}"; - conventions.WriteLongDescription(code.Documentation, + conventions.WriteLongDescription(code, writer, code.Parameters .Where(static x => x.Documentation.DescriptionAvailable) .OrderBy(static x => x.Name, StringComparer.OrdinalIgnoreCase) - .Select(x => $"param {x.Name}: {PythonConventionService.RemoveInvalidDescriptionCharacters(x.Documentation.DescriptionTemplate)}") - .Union(new[] { returnRemark })); + .Select(x => $"param {x.Name}: {x.Documentation.GetDescription(type => conventions.GetTypeString(type, code), normalizationFunc: PythonConventionService.RemoveInvalidDescriptionCharacters)}") + .Union([returnRemark])); conventions.WriteDeprecationWarning(code, writer); } private static readonly PythonCodeParameterOrderComparer parameterOrderComparer = new(); diff --git a/src/Kiota.Builder/Writers/Python/CodePropertyWriter.cs b/src/Kiota.Builder/Writers/Python/CodePropertyWriter.cs index ca963d884f..54d775feab 100644 --- a/src/Kiota.Builder/Writers/Python/CodePropertyWriter.cs +++ b/src/Kiota.Builder/Writers/Python/CodePropertyWriter.cs @@ -27,7 +27,7 @@ public override void WriteCodeElement(CodeProperty codeElement, LanguageWriter w writer.WriteLine("@property"); writer.WriteLine($"def {codeElement.Name}(self) -> {returnType}:"); writer.IncreaseIndent(); - conventions.WriteLongDescription(codeElement.Documentation, writer); + conventions.WriteLongDescription(codeElement, writer); _codeUsingWriter.WriteDeferredImport(parentClass, codeElement.Type.Name, writer); conventions.AddRequestBuilderBody(parentClass, returnType, writer); writer.CloseBlock(string.Empty); @@ -38,14 +38,14 @@ public override void WriteCodeElement(CodeProperty codeElement, LanguageWriter w case CodePropertyKind.Headers: case CodePropertyKind.Options: case CodePropertyKind.QueryParameter: - conventions.WriteInLineDescription(codeElement.Documentation.DescriptionTemplate, writer); + conventions.WriteInLineDescription(codeElement, writer); writer.WriteLine($"{conventions.GetAccessModifier(codeElement.Access)}{codeElement.NamePrefix}{codeElement.Name}: {(codeElement.Type.IsNullable ? "Optional[" : string.Empty)}{returnType}{(codeElement.Type.IsNullable ? "]" : string.Empty)} = None"); writer.WriteLine(); break; case CodePropertyKind.ErrorMessageOverride when parentClass.IsErrorDefinition: writer.WriteLine("@property"); writer.StartBlock($"def {codeElement.Name}(self) -> {codeElement.Type.Name}:"); - conventions.WriteLongDescription(codeElement.Documentation, writer); + conventions.WriteLongDescription(codeElement, writer); if (parentClass.GetPrimaryMessageCodePath(static x => x.Name.ToFirstCharacterLowerCase(), static x => x.Name.ToSnakeCase()) is string primaryMessageCodePath && !string.IsNullOrEmpty(primaryMessageCodePath)) diff --git a/src/Kiota.Builder/Writers/Python/PythonConventionService.cs b/src/Kiota.Builder/Writers/Python/PythonConventionService.cs index cb887fcad1..4f1a146415 100644 --- a/src/Kiota.Builder/Writers/Python/PythonConventionService.cs +++ b/src/Kiota.Builder/Writers/Python/PythonConventionService.cs @@ -155,28 +155,35 @@ private string WriteInlineDeclaration(CodeType currentType, CodeElement targetEl return "object"; return $"{{{innerDeclaration}}}"; } - public override void WriteShortDescription(string description, LanguageWriter writer) + public override void WriteShortDescription(IDocumentedElement element, LanguageWriter writer, string prefix = "", string suffix = "") { ArgumentNullException.ThrowIfNull(writer); - if (!string.IsNullOrEmpty(description)) - { - writer.WriteLine(DocCommentStart); - writer.WriteLine($"{RemoveInvalidDescriptionCharacters(description)}"); - writer.WriteLine(DocCommentEnd); - } + ArgumentNullException.ThrowIfNull(element); + if (!element.Documentation.DescriptionAvailable) return; + if (element is not CodeElement codeElement) return; + + var description = element.Documentation.GetDescription(type => GetTypeString(type, codeElement), normalizationFunc: RemoveInvalidDescriptionCharacters); + writer.WriteLine(DocCommentStart); + writer.WriteLine(description); + writer.WriteLine(DocCommentEnd); } - public void WriteLongDescription(CodeDocumentation documentation, LanguageWriter writer, IEnumerable? additionalRemarks = default) + public void WriteLongDescription(IDocumentedElement element, LanguageWriter writer, IEnumerable? additionalRemarks = default) { ArgumentNullException.ThrowIfNull(writer); - if (documentation is null) return; - if (additionalRemarks == default) - additionalRemarks = Enumerable.Empty(); + ArgumentNullException.ThrowIfNull(element); + if (element.Documentation is not { } documentation) return; + if (element is not CodeElement codeElement) return; + additionalRemarks ??= []; + var additionalRemarksArray = additionalRemarks.ToArray(); if (documentation.DescriptionAvailable || documentation.ExternalDocumentationAvailable || additionalRemarksArray.Length != 0) { writer.WriteLine(DocCommentStart); if (documentation.DescriptionAvailable) - writer.WriteLine($"{RemoveInvalidDescriptionCharacters(documentation.DescriptionTemplate)}"); + { + var description = element.Documentation.GetDescription(type => GetTypeString(type, codeElement), normalizationFunc: RemoveInvalidDescriptionCharacters); + writer.WriteLine($"{description}"); + } foreach (var additionalRemark in additionalRemarksArray.Where(static x => !string.IsNullOrEmpty(x))) writer.WriteLine($"{additionalRemark}"); if (documentation.ExternalDocumentationAvailable) @@ -185,13 +192,14 @@ public void WriteLongDescription(CodeDocumentation documentation, LanguageWriter } } - public void WriteInLineDescription(string description, LanguageWriter writer) + public void WriteInLineDescription(IDocumentedElement element, LanguageWriter writer) { ArgumentNullException.ThrowIfNull(writer); - if (!string.IsNullOrEmpty(description)) - { - writer.WriteLine($"{InLineCommentPrefix}{RemoveInvalidDescriptionCharacters(description)}"); - } + ArgumentNullException.ThrowIfNull(element); + if (!element.Documentation.DescriptionAvailable) return; + if (element is not CodeElement codeElement) return; + var description = element.Documentation.GetDescription(type => GetTypeString(type, codeElement), normalizationFunc: RemoveInvalidDescriptionCharacters); + writer.WriteLine($"{InLineCommentPrefix}{description}"); } private static string GetDeprecationInformation(IDeprecableElement element) diff --git a/src/Kiota.Builder/Writers/Ruby/CodeClassDeclarationWriter.cs b/src/Kiota.Builder/Writers/Ruby/CodeClassDeclarationWriter.cs index f487f14e51..993a0aa482 100644 --- a/src/Kiota.Builder/Writers/Ruby/CodeClassDeclarationWriter.cs +++ b/src/Kiota.Builder/Writers/Ruby/CodeClassDeclarationWriter.cs @@ -54,7 +54,7 @@ public override void WriteCodeElement(ClassDeclaration codeElement, LanguageWrit var derivation = codeElement.Inherits == null ? string.Empty : $" < {conventions.GetNormalizedNamespacePrefixForType(codeElement.Inherits)}{codeElement.Inherits.Name.ToFirstCharacterUpperCase()}"; if (codeElement.Parent is CodeClass parentClass) - conventions.WriteShortDescription(parentClass.Documentation.DescriptionTemplate, writer); + conventions.WriteShortDescription(parentClass, writer); writer.StartBlock($"class {codeElement.Name.ToFirstCharacterUpperCase()}{derivation}"); var mixins = !codeElement.Implements.Any() ? string.Empty : $"include {codeElement.Implements.Select(static x => x.Name).Aggregate(static (x, y) => x + ", " + y)}"; writer.WriteLine($"{mixins}"); diff --git a/src/Kiota.Builder/Writers/Ruby/CodeEnumWriter.cs b/src/Kiota.Builder/Writers/Ruby/CodeEnumWriter.cs index 990ec5a4ff..9b50ea3d6e 100644 --- a/src/Kiota.Builder/Writers/Ruby/CodeEnumWriter.cs +++ b/src/Kiota.Builder/Writers/Ruby/CodeEnumWriter.cs @@ -12,11 +12,11 @@ public override void WriteCodeElement(CodeEnum codeElement, LanguageWriter write { ArgumentNullException.ThrowIfNull(codeElement); ArgumentNullException.ThrowIfNull(writer); - if (!(codeElement?.Options.Any() ?? false)) + if (!codeElement.Options.Any()) return; if (codeElement.Parent is CodeNamespace ns) conventions.WriteNamespaceModules(ns, writer); - conventions.WriteShortDescription(codeElement.Documentation.DescriptionTemplate, writer); + conventions.WriteShortDescription(codeElement, writer); writer.StartBlock($"{codeElement.Name.ToFirstCharacterUpperCase()} = {{"); codeElement.Options.ToList().ForEach(x => writer.WriteLine($"{x.Name.ToFirstCharacterUpperCase()}: :{x.Name.ToFirstCharacterUpperCase()},")); writer.CloseBlock(); diff --git a/src/Kiota.Builder/Writers/Ruby/CodeMethodWriter.cs b/src/Kiota.Builder/Writers/Ruby/CodeMethodWriter.cs index 3d9346fa60..6ff28fe805 100644 --- a/src/Kiota.Builder/Writers/Ruby/CodeMethodWriter.cs +++ b/src/Kiota.Builder/Writers/Ruby/CodeMethodWriter.cs @@ -358,15 +358,20 @@ private void WriteMethodPrototype(CodeMethod code, LanguageWriter writer) } private void WriteMethodDocumentation(CodeMethod code, LanguageWriter writer) { - var isDescriptionPresent = !string.IsNullOrEmpty(code.Documentation.DescriptionTemplate); - var parametersWithDescription = code.Parameters.Where(x => !string.IsNullOrEmpty(code.Documentation.DescriptionTemplate)).OrderBy(static x => x.Name, StringComparer.OrdinalIgnoreCase).ToArray(); - if (isDescriptionPresent || parametersWithDescription.Length != 0) + var parametersWithDescription = code.Parameters.Where(static x => x.Documentation.DescriptionAvailable).OrderBy(static x => x.Name, StringComparer.OrdinalIgnoreCase).ToArray(); + if (code.Documentation.DescriptionAvailable || parametersWithDescription.Length != 0) { writer.WriteLine(conventions.DocCommentStart); - if (isDescriptionPresent) - writer.WriteLine($"{conventions.DocCommentPrefix}{RubyConventionService.RemoveInvalidDescriptionCharacters(code.Documentation.DescriptionTemplate)}"); + if (code.Documentation.DescriptionAvailable) + { + var description = code.Documentation.GetDescription(type => conventions.GetTypeString(type, code), normalizationFunc: RubyConventionService.RemoveInvalidDescriptionCharacters); + writer.WriteLine($"{conventions.DocCommentPrefix}{description}"); + } foreach (var paramWithDescription in parametersWithDescription) - writer.WriteLine($"{conventions.DocCommentPrefix}@param {paramWithDescription.Name.ToSnakeCase()} {RubyConventionService.RemoveInvalidDescriptionCharacters(paramWithDescription.Documentation.DescriptionTemplate)}"); + { + var description = paramWithDescription.Documentation.GetDescription(type => conventions.GetTypeString(type, code), normalizationFunc: RubyConventionService.RemoveInvalidDescriptionCharacters); + writer.WriteLine($"{conventions.DocCommentPrefix}@param {paramWithDescription.Name.ToSnakeCase()} {description}"); + } if (code.IsAsync) writer.WriteLine($"{conventions.DocCommentPrefix}@return a Fiber of {code.ReturnType.Name.ToSnakeCase()}"); diff --git a/src/Kiota.Builder/Writers/Ruby/CodePropertyWriter.cs b/src/Kiota.Builder/Writers/Ruby/CodePropertyWriter.cs index 12810768c6..318125d6c5 100644 --- a/src/Kiota.Builder/Writers/Ruby/CodePropertyWriter.cs +++ b/src/Kiota.Builder/Writers/Ruby/CodePropertyWriter.cs @@ -11,7 +11,7 @@ public override void WriteCodeElement(CodeProperty codeElement, LanguageWriter w ArgumentNullException.ThrowIfNull(codeElement); ArgumentNullException.ThrowIfNull(writer); if (codeElement.ExistsInExternalBaseType) return; - conventions.WriteShortDescription(codeElement.Documentation.DescriptionTemplate, writer); + conventions.WriteShortDescription(codeElement, writer); var returnType = conventions.GetTypeString(codeElement.Type, codeElement); if (codeElement.Parent is not CodeClass parentClass) throw new InvalidOperationException("The parent of a property should be a class"); switch (codeElement.Kind) diff --git a/src/Kiota.Builder/Writers/Ruby/RubyConventionService.cs b/src/Kiota.Builder/Writers/Ruby/RubyConventionService.cs index da307044b6..ea89e6c986 100644 --- a/src/Kiota.Builder/Writers/Ruby/RubyConventionService.cs +++ b/src/Kiota.Builder/Writers/Ruby/RubyConventionService.cs @@ -52,14 +52,16 @@ public override string TranslateType(CodeType type) _ => type.Name.ToFirstCharacterUpperCase() is string typeName && !string.IsNullOrEmpty(typeName) ? typeName : "object", }; } - public override void WriteShortDescription(string description, LanguageWriter writer) + public override void WriteShortDescription(IDocumentedElement element, LanguageWriter writer, string prefix = "", string suffix = "") { ArgumentNullException.ThrowIfNull(writer); - if (!string.IsNullOrEmpty(description)) - { - writer.WriteLine($"{DocCommentPrefix}"); - writer.WriteLine($"# {description}"); - } + ArgumentNullException.ThrowIfNull(element); + if (!element.Documentation.DescriptionAvailable) return; + if (element is not CodeElement codeElement) return; + + var description = element.Documentation.GetDescription(type => GetTypeString(type, codeElement)); + writer.WriteLine($"{DocCommentPrefix}"); + writer.WriteLine($"# {description}"); } #pragma warning disable CA1822 // Method should be static public string GetNormalizedNamespacePrefixForType(CodeTypeBase type) diff --git a/src/Kiota.Builder/Writers/Swift/CodeClassDeclarationWriter.cs b/src/Kiota.Builder/Writers/Swift/CodeClassDeclarationWriter.cs index 4843c18437..5411c52dbe 100644 --- a/src/Kiota.Builder/Writers/Swift/CodeClassDeclarationWriter.cs +++ b/src/Kiota.Builder/Writers/Swift/CodeClassDeclarationWriter.cs @@ -19,7 +19,7 @@ protected override void WriteTypeDeclaration(ClassDeclaration codeElement, Langu .ToArray(); var derivation = derivedTypes.Length != 0 ? ": " + derivedTypes.Select(x => x.ToFirstCharacterUpperCase()).Aggregate(static (x, y) => $"{x}, {y}") + " " : string.Empty; if (codeElement.Parent is CodeClass parentClass) - conventions.WriteShortDescription(parentClass.Documentation.DescriptionTemplate, writer); + conventions.WriteShortDescription(parentClass, writer); writer.WriteLine($"public class {codeElement.Name.ToFirstCharacterUpperCase()} {derivation}{{"); writer.IncreaseIndent(); } diff --git a/src/Kiota.Builder/Writers/Swift/SwiftConventionService.cs b/src/Kiota.Builder/Writers/Swift/SwiftConventionService.cs index d0ef135b86..62edbb6dd2 100644 --- a/src/Kiota.Builder/Writers/Swift/SwiftConventionService.cs +++ b/src/Kiota.Builder/Writers/Swift/SwiftConventionService.cs @@ -20,11 +20,15 @@ public SwiftConventionService(string clientNamespaceName) public static readonly char NullableMarker = '?'; public static string NullableMarkerAsString => "?"; public override string ParseNodeInterfaceName => "ParseNode"; - public override void WriteShortDescription(string description, LanguageWriter writer) + public override void WriteShortDescription(IDocumentedElement element, LanguageWriter writer, string prefix = "", string suffix = "") { ArgumentNullException.ThrowIfNull(writer); - if (!string.IsNullOrEmpty(description)) - writer.WriteLine($"{DocCommentPrefix}{description}"); + ArgumentNullException.ThrowIfNull(element); + if (!element.Documentation.DescriptionAvailable) return; + if (element is not CodeElement codeElement) return; + + var description = element.Documentation.GetDescription(type => GetTypeString(type, codeElement)); + writer.WriteLine($"{DocCommentPrefix}{prefix}{description}{prefix}"); } public override string GetAccessModifier(AccessModifier access) { diff --git a/src/Kiota.Builder/Writers/TypeScript/CodeConstantWriter.cs b/src/Kiota.Builder/Writers/TypeScript/CodeConstantWriter.cs index 33a17b55a0..09388ac8ef 100644 --- a/src/Kiota.Builder/Writers/TypeScript/CodeConstantWriter.cs +++ b/src/Kiota.Builder/Writers/TypeScript/CodeConstantWriter.cs @@ -226,7 +226,7 @@ private void WriteEnumObjectConstant(CodeConstant codeElement, LanguageWriter wr writer.StartBlock($"export const {codeElement.Name.ToFirstCharacterUpperCase()} = {{"); codeEnum.Options.ToList().ForEach(x => { - conventions.WriteShortDescription(x.Documentation.DescriptionTemplate, writer); + conventions.WriteShortDescription(x, writer); writer.WriteLine($"{x.Name.ToFirstCharacterUpperCase()}: \"{x.WireName}\","); }); writer.CloseBlock("} as const;"); diff --git a/src/Kiota.Builder/Writers/TypeScript/CodeMethodWriter.cs b/src/Kiota.Builder/Writers/TypeScript/CodeMethodWriter.cs index ca7bab6eab..1df04c8940 100644 --- a/src/Kiota.Builder/Writers/TypeScript/CodeMethodWriter.cs +++ b/src/Kiota.Builder/Writers/TypeScript/CodeMethodWriter.cs @@ -42,8 +42,8 @@ internal static void WriteMethodDocumentationInternal(CodeMethod code, LanguageW code.Parameters .Where(static x => x.Documentation.DescriptionAvailable) .OrderBy(static x => x.Name) - .Select(x => $"@param {x.Name} {TypeScriptConventionService.RemoveInvalidDescriptionCharacters(x.Documentation.DescriptionTemplate)}") - .Union(new[] { returnRemark })); + .Select(x => $"@param {x.Name} {x.Documentation.GetDescription(type => typeScriptConventionService.GetTypeString(type, code), TypeScriptConventionService.ReferenceTypePrefix, TypeScriptConventionService.ReferenceTypeSuffix, TypeScriptConventionService.RemoveInvalidDescriptionCharacters)}") + .Union([returnRemark])); } private static readonly BaseCodeParameterOrderComparer parameterOrderComparer = new(); private void WriteMethodPrototype(CodeMethod code, LanguageWriter writer, string returnType, bool isVoid) diff --git a/src/Kiota.Builder/Writers/TypeScript/TypeScriptConventionService.cs b/src/Kiota.Builder/Writers/TypeScript/TypeScriptConventionService.cs index d724c79795..3b0e16617e 100644 --- a/src/Kiota.Builder/Writers/TypeScript/TypeScriptConventionService.cs +++ b/src/Kiota.Builder/Writers/TypeScript/TypeScriptConventionService.cs @@ -132,25 +132,34 @@ public bool IsPrimitiveType(string typeName) } #pragma warning restore CA1822 // Method should be static internal static string RemoveInvalidDescriptionCharacters(string originalDescription) => originalDescription?.Replace("\\", "/", StringComparison.OrdinalIgnoreCase) ?? string.Empty; - public override void WriteShortDescription(string description, LanguageWriter writer) + public override void WriteShortDescription(IDocumentedElement element, LanguageWriter writer, string prefix = "", string suffix = "") { ArgumentNullException.ThrowIfNull(writer); - if (!string.IsNullOrEmpty(description)) - writer.WriteLine($"{DocCommentStart} {RemoveInvalidDescriptionCharacters(description)}{DocCommentEnd}"); + ArgumentNullException.ThrowIfNull(element); + if (!element.Documentation.DescriptionAvailable) return; + if (element is not CodeElement codeElement) return; + + var description = element.Documentation.GetDescription(type => GetTypeString(type, codeElement), ReferenceTypePrefix, ReferenceTypeSuffix, RemoveInvalidDescriptionCharacters); + writer.WriteLine($"{DocCommentStart} {description}{DocCommentEnd}"); } + internal const string ReferenceTypePrefix = "{@link "; + internal const string ReferenceTypeSuffix = "}"; public void WriteLongDescription(IDocumentedElement documentedElement, LanguageWriter writer, IEnumerable? additionalRemarks = default) { ArgumentNullException.ThrowIfNull(writer); ArgumentNullException.ThrowIfNull(documentedElement); if (documentedElement.Documentation is null) return; - if (additionalRemarks == default) - additionalRemarks = Enumerable.Empty(); + if (documentedElement is not CodeElement codeElement) return; + additionalRemarks ??= []; var remarks = additionalRemarks.Where(static x => !string.IsNullOrEmpty(x)).ToArray(); if (documentedElement.Documentation.DescriptionAvailable || documentedElement.Documentation.ExternalDocumentationAvailable || remarks.Length != 0) { writer.WriteLine(DocCommentStart); if (documentedElement.Documentation.DescriptionAvailable) - writer.WriteLine($"{DocCommentPrefix}{RemoveInvalidDescriptionCharacters(documentedElement.Documentation.DescriptionTemplate)}"); + { + var description = documentedElement.Documentation.GetDescription(type => GetTypeString(type, codeElement), ReferenceTypePrefix, ReferenceTypeSuffix, RemoveInvalidDescriptionCharacters); + writer.WriteLine($"{DocCommentPrefix}{description}"); + } foreach (var additionalRemark in remarks) writer.WriteLine($"{DocCommentPrefix}{additionalRemark}"); From f3997c2d31ce10c2e8e1c822a41e82bf431997e9 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Fri, 2 Feb 2024 09:23:42 -0500 Subject: [PATCH 10/21] - fixes regession for position parameter in indexer --- src/Kiota.Builder/Writers/CSharp/CodeIndexerWriter.cs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Kiota.Builder/Writers/CSharp/CodeIndexerWriter.cs b/src/Kiota.Builder/Writers/CSharp/CodeIndexerWriter.cs index ae27c1c982..64b3cc92c9 100644 --- a/src/Kiota.Builder/Writers/CSharp/CodeIndexerWriter.cs +++ b/src/Kiota.Builder/Writers/CSharp/CodeIndexerWriter.cs @@ -13,7 +13,7 @@ public override void WriteCodeElement(CodeIndexer codeElement, LanguageWriter wr if (codeElement.Parent is not CodeClass parentClass) throw new InvalidOperationException("The parent of a property should be a class"); var returnType = conventions.GetTypeString(codeElement.ReturnType, codeElement); conventions.WriteShortDescription(codeElement, writer); - conventions.WriteShortDescription(codeElement.IndexParameter, writer, $"", ""); + conventions.WriteShortDescription(codeElement.IndexParameter, writer, $"", ""); conventions.WriteDeprecationAttribute(codeElement, writer); writer.StartBlock($"public {returnType} this[{conventions.GetTypeString(codeElement.IndexParameter.Type, codeElement)} position] {{ get {{"); if (parentClass.GetPropertyOfKind(CodePropertyKind.PathParameters) is CodeProperty pathParametersProp) From ea41664bf9b0ed79603870a84bfd4150fea256dd Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Fri, 2 Feb 2024 10:18:09 -0500 Subject: [PATCH 11/21] - adds thrown exceptions doc comments support for dotnet --- .../Writers/CSharp/CSharpConventionService.cs | 6 ++++++ .../Writers/CSharp/CodeIndexerWriter.cs | 2 +- .../Writers/CSharp/CodeMethodWriter.cs | 14 ++++++++++++++ .../Writers/CSharp/CodeMethodWriterTests.cs | 5 +++++ 4 files changed, 26 insertions(+), 1 deletion(-) diff --git a/src/Kiota.Builder/Writers/CSharp/CSharpConventionService.cs b/src/Kiota.Builder/Writers/CSharp/CSharpConventionService.cs index 7cd4558bed..9a965ca619 100644 --- a/src/Kiota.Builder/Writers/CSharp/CSharpConventionService.cs +++ b/src/Kiota.Builder/Writers/CSharp/CSharpConventionService.cs @@ -47,6 +47,12 @@ public override void WriteShortDescription(IDocumentedElement element, LanguageW var description = element.Documentation.GetDescription(type => GetTypeString(type, codeElement), ReferenceTypePrefix, ReferenceTypeSuffix, static x => x.CleanupXMLString()); writer.WriteLine($"{DocCommentPrefix}{prefix}{description}{suffix}"); } + public void WriteAdditionalDescriptionItem(string description, LanguageWriter writer) + { + ArgumentNullException.ThrowIfNull(writer); + ArgumentNullException.ThrowIfNull(description); + writer.WriteLine($"{DocCommentPrefix}{description}"); + } public void WriteLongDescription(IDocumentedElement element, LanguageWriter writer) { ArgumentNullException.ThrowIfNull(writer); diff --git a/src/Kiota.Builder/Writers/CSharp/CodeIndexerWriter.cs b/src/Kiota.Builder/Writers/CSharp/CodeIndexerWriter.cs index 64b3cc92c9..7ed4144f71 100644 --- a/src/Kiota.Builder/Writers/CSharp/CodeIndexerWriter.cs +++ b/src/Kiota.Builder/Writers/CSharp/CodeIndexerWriter.cs @@ -12,7 +12,7 @@ public override void WriteCodeElement(CodeIndexer codeElement, LanguageWriter wr ArgumentNullException.ThrowIfNull(writer); if (codeElement.Parent is not CodeClass parentClass) throw new InvalidOperationException("The parent of a property should be a class"); var returnType = conventions.GetTypeString(codeElement.ReturnType, codeElement); - conventions.WriteShortDescription(codeElement, writer); + conventions.WriteShortDescription(codeElement, writer);//TODO make the parameter name dynamic in v2 conventions.WriteShortDescription(codeElement.IndexParameter, writer, $"", ""); conventions.WriteDeprecationAttribute(codeElement, writer); writer.StartBlock($"public {returnType} this[{conventions.GetTypeString(codeElement.IndexParameter.Type, codeElement)} position] {{ get {{"); diff --git a/src/Kiota.Builder/Writers/CSharp/CodeMethodWriter.cs b/src/Kiota.Builder/Writers/CSharp/CodeMethodWriter.cs index 85b27d1c1b..ea72433b98 100644 --- a/src/Kiota.Builder/Writers/CSharp/CodeMethodWriter.cs +++ b/src/Kiota.Builder/Writers/CSharp/CodeMethodWriter.cs @@ -546,8 +546,22 @@ private void WriteMethodDocumentation(CodeMethod code, LanguageWriter writer) .Where(static x => x.Documentation.DescriptionAvailable) .OrderBy(static x => x.Name, StringComparer.OrdinalIgnoreCase)) conventions.WriteShortDescription(paramWithDescription, writer, $"", ""); + WriteThrownExceptions(code, writer); conventions.WriteDeprecationAttribute(code, writer); } + private void WriteThrownExceptions(CodeMethod element, LanguageWriter writer) + { + if (element.Kind is not CodeMethodKind.RequestExecutor) return; + foreach (var exception in element.ErrorMappings) + { + var statusCode = exception.Key.ToUpperInvariant() switch + { + "XXX" => "4XX or 5XX", + _ => exception.Key, + }; + conventions.WriteAdditionalDescriptionItem($"When receiving a {statusCode} status code", writer); + } + } private static readonly BaseCodeParameterOrderComparer parameterOrderComparer = new(); private static string GetBaseSuffix(bool isConstructor, bool inherits, CodeClass parentClass, CodeMethod currentMethod) { diff --git a/tests/Kiota.Builder.Tests/Writers/CSharp/CodeMethodWriterTests.cs b/tests/Kiota.Builder.Tests/Writers/CSharp/CodeMethodWriterTests.cs index bb15cda15e..05d21a87da 100644 --- a/tests/Kiota.Builder.Tests/Writers/CSharp/CodeMethodWriterTests.cs +++ b/tests/Kiota.Builder.Tests/Writers/CSharp/CodeMethodWriterTests.cs @@ -470,6 +470,7 @@ public void WritesRequestExecutorBody() var result = tw.ToString(); Assert.Contains("var requestInfo", result); Assert.Contains("var errorMapping = new Dictionary>", result); + Assert.Contains("", result); + Assert.Contains(" Date: Fri, 2 Feb 2024 11:39:12 -0500 Subject: [PATCH 12/21] - adds missing return doc comments for CSharp Signed-off-by: Vincent Biret --- src/Kiota.Builder/Writers/CSharp/CodeIndexerWriter.cs | 1 + src/Kiota.Builder/Writers/CSharp/CodeMethodWriter.cs | 2 ++ .../Writers/CSharp/CodeIndexerWriterTests.cs | 2 ++ 3 files changed, 5 insertions(+) diff --git a/src/Kiota.Builder/Writers/CSharp/CodeIndexerWriter.cs b/src/Kiota.Builder/Writers/CSharp/CodeIndexerWriter.cs index 7ed4144f71..cde95bac5b 100644 --- a/src/Kiota.Builder/Writers/CSharp/CodeIndexerWriter.cs +++ b/src/Kiota.Builder/Writers/CSharp/CodeIndexerWriter.cs @@ -14,6 +14,7 @@ public override void WriteCodeElement(CodeIndexer codeElement, LanguageWriter wr var returnType = conventions.GetTypeString(codeElement.ReturnType, codeElement); conventions.WriteShortDescription(codeElement, writer);//TODO make the parameter name dynamic in v2 conventions.WriteShortDescription(codeElement.IndexParameter, writer, $"", ""); + conventions.WriteAdditionalDescriptionItem($"A ", writer); conventions.WriteDeprecationAttribute(codeElement, writer); writer.StartBlock($"public {returnType} this[{conventions.GetTypeString(codeElement.IndexParameter.Type, codeElement)} position] {{ get {{"); if (parentClass.GetPropertyOfKind(CodePropertyKind.PathParameters) is CodeProperty pathParametersProp) diff --git a/src/Kiota.Builder/Writers/CSharp/CodeMethodWriter.cs b/src/Kiota.Builder/Writers/CSharp/CodeMethodWriter.cs index ea72433b98..65e75ae003 100644 --- a/src/Kiota.Builder/Writers/CSharp/CodeMethodWriter.cs +++ b/src/Kiota.Builder/Writers/CSharp/CodeMethodWriter.cs @@ -542,6 +542,8 @@ protected string GetSendRequestMethodName(bool isVoid, CodeElement currentElemen private void WriteMethodDocumentation(CodeMethod code, LanguageWriter writer) { conventions.WriteLongDescription(code, writer); + if (!"void".Equals(code.ReturnType.Name, StringComparison.OrdinalIgnoreCase) && code.Kind is not CodeMethodKind.ClientConstructor or CodeMethodKind.Constructor) + conventions.WriteAdditionalDescriptionItem($"A ", writer); foreach (var paramWithDescription in code.Parameters .Where(static x => x.Documentation.DescriptionAvailable) .OrderBy(static x => x.Name, StringComparer.OrdinalIgnoreCase)) diff --git a/tests/Kiota.Builder.Tests/Writers/CSharp/CodeIndexerWriterTests.cs b/tests/Kiota.Builder.Tests/Writers/CSharp/CodeIndexerWriterTests.cs index 93bec8f238..a55e1d7e63 100644 --- a/tests/Kiota.Builder.Tests/Writers/CSharp/CodeIndexerWriterTests.cs +++ b/tests/Kiota.Builder.Tests/Writers/CSharp/CodeIndexerWriterTests.cs @@ -81,6 +81,8 @@ public void WritesIndexer() Assert.Contains("id\", position", result); Assert.Contains("some description", result); Assert.Contains("public SomeRequestBuilder this[string position]", result); + Assert.Contains("return new SomeRequestBuilder(urlTplParams, RequestAdapter);", result); + Assert.Contains("", result); AssertExtensions.CurlyBracesAreClosed(result); } } From 5aab564d86177c5e4dd4dff9f1bf031cc8dc9a22 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Fri, 2 Feb 2024 12:56:09 -0500 Subject: [PATCH 13/21] - adds missing return doc comment to java - adds link to types for javadoc Signed-off-by: Vincent Biret --- .../Writers/Java/CodeMethodWriter.cs | 4 ++-- .../Writers/Java/CodePropertyWriter.cs | 6 ++++-- .../Writers/Java/JavaConventionService.cs | 20 ++++++++++++++----- .../Writers/Java/CodeMethodWriterTests.cs | 2 ++ 4 files changed, 23 insertions(+), 9 deletions(-) diff --git a/src/Kiota.Builder/Writers/Java/CodeMethodWriter.cs b/src/Kiota.Builder/Writers/Java/CodeMethodWriter.cs index 639f42f6de..d3e33feaff 100644 --- a/src/Kiota.Builder/Writers/Java/CodeMethodWriter.cs +++ b/src/Kiota.Builder/Writers/Java/CodeMethodWriter.cs @@ -737,13 +737,13 @@ private void WriteMethodDocumentation(CodeMethod code, LanguageWriter writer, st { var returnVoid = baseReturnType.Equals("void", StringComparison.OrdinalIgnoreCase); // Void returns, this includes constructors, should not have a return statement in the JavaDocs. - var returnRemark = returnVoid ? string.Empty : $"@return a {finalReturnType}"; + var returnRemark = returnVoid ? string.Empty : conventions.GetReturnDocComment(finalReturnType); conventions.WriteLongDescription(code, writer, code.Parameters .Where(static x => x.Documentation.DescriptionAvailable) .OrderBy(static x => x.Name, StringComparer.OrdinalIgnoreCase) - .Select(x => $"@param {x.Name} {x.Documentation.GetDescription(y => conventions.GetTypeString(y, code), normalizationFunc: JavaConventionService.RemoveInvalidDescriptionCharacters)}") + .Select(x => $"@param {x.Name} {x.Documentation.GetDescription(y => conventions.GetTypeReferenceForDocComment(y, code), normalizationFunc: JavaConventionService.RemoveInvalidDescriptionCharacters)}") .Union([returnRemark])); if (!returnVoid) //Nullable/Nonnull annotations for returns are a part of Method Documentation writer.WriteLine(code.ReturnType.IsNullable ? "@jakarta.annotation.Nullable" : "@jakarta.annotation.Nonnull"); diff --git a/src/Kiota.Builder/Writers/Java/CodePropertyWriter.cs b/src/Kiota.Builder/Writers/Java/CodePropertyWriter.cs index 61dc35b4a1..0f429430f0 100644 --- a/src/Kiota.Builder/Writers/Java/CodePropertyWriter.cs +++ b/src/Kiota.Builder/Writers/Java/CodePropertyWriter.cs @@ -1,6 +1,5 @@ using System; using Kiota.Builder.CodeDOM; -using Kiota.Builder.Extensions; namespace Kiota.Builder.Writers.Java; public class CodePropertyWriter : BaseElementWriter @@ -13,8 +12,11 @@ public override void WriteCodeElement(CodeProperty codeElement, LanguageWriter w if (codeElement.ExistsInExternalBaseType) return; if (codeElement.Parent is not CodeClass parentClass) throw new InvalidOperationException("The parent of a property should be a class"); - conventions.WriteLongDescription(codeElement, writer); var returnType = conventions.GetTypeString(codeElement.Type, codeElement); + var returnRemark = codeElement.Kind is CodePropertyKind.RequestBuilder ? + conventions.GetReturnDocComment(returnType) : + string.Empty; + conventions.WriteLongDescription(codeElement, writer, [returnRemark]); var defaultValue = string.Empty; conventions.WriteDeprecatedAnnotation(codeElement, writer); switch (codeElement.Kind) diff --git a/src/Kiota.Builder/Writers/Java/JavaConventionService.cs b/src/Kiota.Builder/Writers/Java/JavaConventionService.cs index 088867a10e..314a0404a5 100644 --- a/src/Kiota.Builder/Writers/Java/JavaConventionService.cs +++ b/src/Kiota.Builder/Writers/Java/JavaConventionService.cs @@ -92,7 +92,11 @@ _ when type.Name.Contains('.', StringComparison.OrdinalIgnoreCase) => type.Name, _ => type.Name is string typeName && !string.IsNullOrEmpty(typeName) ? typeName : "Object", }; } - private const string ReferenceTypePrefix = "{@link #"; + internal string GetReturnDocComment(string returnType) + { + return $"@return a {ReferenceTypePrefix}{returnType}{ReferenceTypeSuffix}"; + } + private const string ReferenceTypePrefix = "{@link "; private const string ReferenceTypeSuffix = "}"; public override void WriteShortDescription(IDocumentedElement element, LanguageWriter writer, string prefix = "", string suffix = "") { @@ -101,26 +105,32 @@ public override void WriteShortDescription(IDocumentedElement element, LanguageW if (!element.Documentation.DescriptionAvailable) return; if (element is not CodeElement codeElement) return; - var description = element.Documentation.GetDescription(x => GetTypeString(x, codeElement), ReferenceTypePrefix, ReferenceTypeSuffix, RemoveInvalidDescriptionCharacters); + var description = element.Documentation.GetDescription(x => GetTypeReferenceForDocComment(x, codeElement), ReferenceTypePrefix, ReferenceTypeSuffix, RemoveInvalidDescriptionCharacters); writer.WriteLine($"{DocCommentStart} {description}{DocCommentEnd}"); } + internal string GetTypeReferenceForDocComment(CodeTypeBase code, CodeElement targetElement) + { + if (code is CodeType codeType && codeType.TypeDefinition is CodeMethod method) + return $"{GetTypeString(new CodeType { TypeDefinition = method.Parent, IsExternal = false }, targetElement)}#{GetTypeString(code, targetElement)}"; + return $"{GetTypeString(code, targetElement)}"; + } public void WriteLongDescription(CodeElement element, LanguageWriter writer, IEnumerable? additionalRemarks = default) { ArgumentNullException.ThrowIfNull(writer); if (element is not IDocumentedElement documentedElement || documentedElement.Documentation is not CodeDocumentation documentation) return; if (additionalRemarks == default) additionalRemarks = []; - var remarks = additionalRemarks.ToArray(); + var remarks = additionalRemarks.Where(static x => !string.IsNullOrEmpty(x)).ToArray(); if (documentation.DescriptionAvailable || documentation.ExternalDocumentationAvailable || remarks.Length != 0) { writer.WriteLine(DocCommentStart); if (documentation.DescriptionAvailable) { - var description = documentedElement.Documentation.GetDescription(x => GetTypeString(x, element), ReferenceTypePrefix, ReferenceTypeSuffix, RemoveInvalidDescriptionCharacters); + var description = documentedElement.Documentation.GetDescription(x => GetTypeReferenceForDocComment(x, element), ReferenceTypePrefix, ReferenceTypeSuffix, RemoveInvalidDescriptionCharacters); writer.WriteLine($"{DocCommentPrefix}{description}"); } - foreach (var additionalRemark in remarks.Where(static x => !string.IsNullOrEmpty(x))) + foreach (var additionalRemark in remarks) writer.WriteLine($"{DocCommentPrefix}{additionalRemark}"); if (element is IDeprecableElement deprecableElement && deprecableElement.Deprecation is not null && deprecableElement.Deprecation.IsDeprecated) foreach (var additionalComment in GetDeprecationInformationForDocumentationComment(deprecableElement)) diff --git a/tests/Kiota.Builder.Tests/Writers/Java/CodeMethodWriterTests.cs b/tests/Kiota.Builder.Tests/Writers/Java/CodeMethodWriterTests.cs index 635df542a1..1e390cd22f 100644 --- a/tests/Kiota.Builder.Tests/Writers/Java/CodeMethodWriterTests.cs +++ b/tests/Kiota.Builder.Tests/Writers/Java/CodeMethodWriterTests.cs @@ -654,6 +654,8 @@ public void WritesRequestExecutorBody() Assert.Contains("put(\"5XX\", Error5XX::createFromDiscriminatorValue);", result); Assert.Contains("put(\"401\", Error401::createFromDiscriminatorValue);", result); Assert.Contains("send", result); + Assert.Contains("@return", result); + Assert.Contains("@link", result); AssertExtensions.CurlyBracesAreClosed(result); } [Fact] From 5b6326190a48c8dd19b6322d3e8f63b7d3295a78 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Fri, 2 Feb 2024 13:08:04 -0500 Subject: [PATCH 14/21] - adds support for exception thrown in java doc comments Signed-off-by: Vincent Biret --- .../Writers/Java/CodeMethodWriter.cs | 19 ++++++++++++++++++- .../Writers/Java/CodeMethodWriterTests.cs | 1 + 2 files changed, 19 insertions(+), 1 deletion(-) diff --git a/src/Kiota.Builder/Writers/Java/CodeMethodWriter.cs b/src/Kiota.Builder/Writers/Java/CodeMethodWriter.cs index d3e33feaff..c542d9ca51 100644 --- a/src/Kiota.Builder/Writers/Java/CodeMethodWriter.cs +++ b/src/Kiota.Builder/Writers/Java/CodeMethodWriter.cs @@ -744,10 +744,27 @@ private void WriteMethodDocumentation(CodeMethod code, LanguageWriter writer, st .Where(static x => x.Documentation.DescriptionAvailable) .OrderBy(static x => x.Name, StringComparer.OrdinalIgnoreCase) .Select(x => $"@param {x.Name} {x.Documentation.GetDescription(y => conventions.GetTypeReferenceForDocComment(y, code), normalizationFunc: JavaConventionService.RemoveInvalidDescriptionCharacters)}") - .Union([returnRemark])); + .Union([returnRemark]) + .Union(GetExceptionDocRemarks(code))); if (!returnVoid) //Nullable/Nonnull annotations for returns are a part of Method Documentation writer.WriteLine(code.ReturnType.IsNullable ? "@jakarta.annotation.Nullable" : "@jakarta.annotation.Nonnull"); } + private IEnumerable GetExceptionDocRemarks(CodeMethod code) + { + if (code.Kind is not CodeMethodKind.RequestExecutor) + yield break; + + foreach (var errorMapping in code.ErrorMappings) + { + var statusCode = errorMapping.Key.ToUpperInvariant() switch + { + "XXX" => "4XX or 5XX", + _ => errorMapping.Key, + }; + var errorTypeString = conventions.GetTypeString(errorMapping.Value, code); + yield return $"@throws {errorTypeString} When receiving a {statusCode} status code"; + } + } private string GetDeserializationMethodName(CodeTypeBase propType, CodeMethod method) { var isCollection = propType.CollectionKind != CodeTypeBase.CodeTypeCollectionKind.None; diff --git a/tests/Kiota.Builder.Tests/Writers/Java/CodeMethodWriterTests.cs b/tests/Kiota.Builder.Tests/Writers/Java/CodeMethodWriterTests.cs index 1e390cd22f..fb3bbacc5c 100644 --- a/tests/Kiota.Builder.Tests/Writers/Java/CodeMethodWriterTests.cs +++ b/tests/Kiota.Builder.Tests/Writers/Java/CodeMethodWriterTests.cs @@ -656,6 +656,7 @@ public void WritesRequestExecutorBody() Assert.Contains("send", result); Assert.Contains("@return", result); Assert.Contains("@link", result); + Assert.Contains("@throws", result); AssertExtensions.CurlyBracesAreClosed(result); } [Fact] From 33b13f392b3f811ce294f5af8a706ffac4d9ac3b Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Fri, 2 Feb 2024 13:19:39 -0500 Subject: [PATCH 15/21] - fixes type doc comment syntax in go - does not emit comment if no description is available in go Signed-off-by: Vincent Biret --- src/Kiota.Builder/Writers/Go/CodeClassDeclarationWriter.cs | 2 +- src/Kiota.Builder/Writers/Go/GoConventionService.cs | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/Kiota.Builder/Writers/Go/CodeClassDeclarationWriter.cs b/src/Kiota.Builder/Writers/Go/CodeClassDeclarationWriter.cs index b8e77e213e..6e7c26b7f9 100644 --- a/src/Kiota.Builder/Writers/Go/CodeClassDeclarationWriter.cs +++ b/src/Kiota.Builder/Writers/Go/CodeClassDeclarationWriter.cs @@ -15,7 +15,7 @@ protected override void WriteTypeDeclaration(ClassDeclaration codeElement, Langu ArgumentNullException.ThrowIfNull(writer); var className = codeElement.Name.ToFirstCharacterUpperCase(); if (codeElement.Parent is not CodeClass currentClass) throw new InvalidOperationException("The parent of a class declaration should be a class"); - conventions.WriteShortDescription(currentClass, writer, $"A {className}"); + conventions.WriteShortDescription(currentClass, writer, $"{className} "); conventions.WriteDeprecation(currentClass, writer); conventions.WriteLinkDescription(currentClass.Documentation, writer); writer.StartBlock($"type {className} struct {{"); diff --git a/src/Kiota.Builder/Writers/Go/GoConventionService.cs b/src/Kiota.Builder/Writers/Go/GoConventionService.cs index 24f08cbc05..6f45943e74 100644 --- a/src/Kiota.Builder/Writers/Go/GoConventionService.cs +++ b/src/Kiota.Builder/Writers/Go/GoConventionService.cs @@ -173,7 +173,7 @@ public override void WriteShortDescription(IDocumentedElement element, LanguageW if (!element.Documentation.DescriptionAvailable) return; if (element is not CodeElement codeElement) return; - var description = element.Documentation.GetDescription(x => GetTypeString(x, codeElement)); + var description = element.Documentation.GetDescription(x => GetTypeString(x, codeElement, true, false)); if (!string.IsNullOrEmpty(prefix)) { description = description.ToFirstCharacterLowerCase(); From 723d73ff04b2d688f61a6a38403decc3960f44a9 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Fri, 2 Feb 2024 14:08:55 -0500 Subject: [PATCH 16/21] - adds missing return doc comment in go - adds throws doc comment in go Signed-off-by: Vincent Biret --- .../Writers/Go/CodeMethodWriter.cs | 20 +++++++++++++++++++ .../Writers/Go/GoConventionService.cs | 2 +- .../Writers/Go/CodeMethodWriterTests.cs | 1 + 3 files changed, 22 insertions(+), 1 deletion(-) diff --git a/src/Kiota.Builder/Writers/Go/CodeMethodWriter.cs b/src/Kiota.Builder/Writers/Go/CodeMethodWriter.cs index ee709bed1c..16b4a4fc44 100644 --- a/src/Kiota.Builder/Writers/Go/CodeMethodWriter.cs +++ b/src/Kiota.Builder/Writers/Go/CodeMethodWriter.cs @@ -292,8 +292,28 @@ private void WriteMethodDocumentation(CodeMethod code, string methodName, Langua { conventions.WriteShortDescription(code, writer, $"{methodName.ToFirstCharacterUpperCase()} "); conventions.WriteDeprecation(code, writer); + if (!"void".Equals(code.ReturnType.Name, StringComparison.OrdinalIgnoreCase)) + { + var shortReturnTypeName = conventions.GetTypeString(code.ReturnType, code, true, true, false); + conventions.WriteDescriptionItem($"returns a {shortReturnTypeName} when successful", writer); + } + WriteThrownExceptions(code, writer); conventions.WriteLinkDescription(code.Documentation, writer); } + private void WriteThrownExceptions(CodeMethod code, LanguageWriter writer) + { + if (code.Kind is not CodeMethodKind.RequestExecutor) return; + foreach (var errorMapping in code.ErrorMappings) + { + var statusCode = errorMapping.Key.ToUpperInvariant() switch + { + "XXX" => "4XX or 5XX", + _ => errorMapping.Key, + }; + var errorTypeString = conventions.GetTypeString(errorMapping.Value, code, false, false, false); + conventions.WriteDescriptionItem($"returns a {errorTypeString} error when the service returns a {statusCode} status code", writer); + } + } private const string TempParamsVarName = "urlParams"; private static void WriteRawUrlConstructorBody(CodeClass parentClass, CodeMethod codeElement, LanguageWriter writer) { diff --git a/src/Kiota.Builder/Writers/Go/GoConventionService.cs b/src/Kiota.Builder/Writers/Go/GoConventionService.cs index 6f45943e74..fc4c739d58 100644 --- a/src/Kiota.Builder/Writers/Go/GoConventionService.cs +++ b/src/Kiota.Builder/Writers/Go/GoConventionService.cs @@ -54,7 +54,7 @@ public string GetTypeString(CodeTypeBase code, CodeElement targetElement, bool i throw new InvalidOperationException($"Go does not support union types, the union type {code.Name} should have been filtered out by the refiner"); if (code is CodeType currentType) { - var importSymbol = GetImportSymbol(code, targetElement); + var importSymbol = includeImportSymbol ? GetImportSymbol(code, targetElement) : string.Empty; if (!string.IsNullOrEmpty(importSymbol)) importSymbol += "."; var typeName = TranslateType(currentType, includeImportSymbol); diff --git a/tests/Kiota.Builder.Tests/Writers/Go/CodeMethodWriterTests.cs b/tests/Kiota.Builder.Tests/Writers/Go/CodeMethodWriterTests.cs index cda1087fd7..ba7289a149 100644 --- a/tests/Kiota.Builder.Tests/Writers/Go/CodeMethodWriterTests.cs +++ b/tests/Kiota.Builder.Tests/Writers/Go/CodeMethodWriterTests.cs @@ -718,6 +718,7 @@ public void WritesRequestExecutorBody() Assert.Contains("return nil, err", result); Assert.Contains("if res == nil", result); Assert.Contains("return nil, nil", result); + Assert.Contains("returns", result); AssertExtensions.CurlyBracesAreClosed(result); } [Fact] From fe3efe825a28436a6d8029045b15f2fb0e44bc1e Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Fri, 2 Feb 2024 14:38:28 -0500 Subject: [PATCH 17/21] - adds support for thrown exception doc comments in typescript - fixes jsdoc implementation of return type in typescript Signed-off-by: Vincent Biret --- .../Writers/TypeScript/CodeMethodWriter.cs | 22 ++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) diff --git a/src/Kiota.Builder/Writers/TypeScript/CodeMethodWriter.cs b/src/Kiota.Builder/Writers/TypeScript/CodeMethodWriter.cs index 1df04c8940..2e9a99cc3b 100644 --- a/src/Kiota.Builder/Writers/TypeScript/CodeMethodWriter.cs +++ b/src/Kiota.Builder/Writers/TypeScript/CodeMethodWriter.cs @@ -1,4 +1,5 @@ using System; +using System.Collections.Generic; using System.Linq; using Kiota.Builder.CodeDOM; using Kiota.Builder.Extensions; @@ -34,8 +35,8 @@ internal static void WriteMethodDocumentationInternal(CodeMethod code, LanguageW var returnRemark = (isVoid, code.IsAsync) switch { (true, _) => string.Empty, - (false, true) => $"@returns a Promise of {code.ReturnType.Name.ToFirstCharacterUpperCase()}", - (false, false) => $"@returns a {code.ReturnType.Name}", + (false, true) => $"@returns {{Promise<{typeScriptConventionService.GetTypeString(code.ReturnType, code)}>}}", + (false, false) => $"@returns {{{typeScriptConventionService.GetTypeString(code.ReturnType, code)}}}", }; typeScriptConventionService.WriteLongDescription(code, writer, @@ -43,7 +44,22 @@ internal static void WriteMethodDocumentationInternal(CodeMethod code, LanguageW .Where(static x => x.Documentation.DescriptionAvailable) .OrderBy(static x => x.Name) .Select(x => $"@param {x.Name} {x.Documentation.GetDescription(type => typeScriptConventionService.GetTypeString(type, code), TypeScriptConventionService.ReferenceTypePrefix, TypeScriptConventionService.ReferenceTypeSuffix, TypeScriptConventionService.RemoveInvalidDescriptionCharacters)}") - .Union([returnRemark])); + .Union([returnRemark]) + .Union(GetThrownExceptionsRemarks(code, typeScriptConventionService))); + } + private static IEnumerable GetThrownExceptionsRemarks(CodeMethod code, TypeScriptConventionService typeScriptConventionService) + { + if (code.Kind is not CodeMethodKind.RequestExecutor) yield break; + foreach (var errorMapping in code.ErrorMappings) + { + var statusCode = errorMapping.Key.ToUpperInvariant() switch + { + "XXX" => "4XX or 5XX", + _ => errorMapping.Key, + }; + var errorTypeString = typeScriptConventionService.GetTypeString(errorMapping.Value, code, false); + yield return $"@throws {{{errorTypeString}}} error when the service returns a {statusCode} status code"; + } } private static readonly BaseCodeParameterOrderComparer parameterOrderComparer = new(); private void WriteMethodPrototype(CodeMethod code, LanguageWriter writer, string returnType, bool isVoid) From 573ed9a84a811396351d605f99e1c2b0a602f409 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Fri, 2 Feb 2024 14:40:22 -0500 Subject: [PATCH 18/21] - adds changelog entries for doc comments improvements --- CHANGELOG.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9c98c551eb..e59d56c6f2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Keyword in enum names for go should not be escaped. [#2877](https://github.com/microsoft/kiota/issues/2877) - Generator method code reduction in Python. [#3695](https://github.com/microsoft/kiota/issues/3695) +- Fixed return doc comments for Go/Java/CSharp/TypeScript. +- Fixed type names in doc comments and deprecation noticed across languages. +- Added thrown exceptions in doc comments for Go/CSharp/Java/TypeScript. [#3811](https://github.com/microsoft/kiota/issues/3811) + ## [1.11.1] - 2024-02-05 ### Added From 3639f412c87a66f525fe85fa7e71000feeab9cc4 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Fri, 2 Feb 2024 14:48:11 -0500 Subject: [PATCH 19/21] - fixed formatting --- src/Kiota.Builder/CodeDOM/CodeDocumentation.cs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Kiota.Builder/CodeDOM/CodeDocumentation.cs b/src/Kiota.Builder/CodeDOM/CodeDocumentation.cs index 2d8035fb76..5fd6219455 100644 --- a/src/Kiota.Builder/CodeDOM/CodeDocumentation.cs +++ b/src/Kiota.Builder/CodeDOM/CodeDocumentation.cs @@ -1,6 +1,6 @@ using System; -using System.Collections.Generic; using System.Collections.Concurrent; +using System.Collections.Generic; using System.Linq; namespace Kiota.Builder.CodeDOM; From 641a20a1fb6044c7d12f9d5f6303091b7d01a4a5 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Fri, 2 Feb 2024 14:50:43 -0500 Subject: [PATCH 20/21] - fixes failing test --- .../Writers/TypeScript/CodeFunctionWriterTests.cs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/Kiota.Builder.Tests/Writers/TypeScript/CodeFunctionWriterTests.cs b/tests/Kiota.Builder.Tests/Writers/TypeScript/CodeFunctionWriterTests.cs index a3bbd00f73..cb9856a699 100644 --- a/tests/Kiota.Builder.Tests/Writers/TypeScript/CodeFunctionWriterTests.cs +++ b/tests/Kiota.Builder.Tests/Writers/TypeScript/CodeFunctionWriterTests.cs @@ -851,7 +851,7 @@ public void DoesNotAddUndefinedOnNonNullableReturnType() root.TryAddCodeFile("foo", function); writer.Write(function); var result = tw.ToString(); - Assert.DoesNotContain("| undefined", result.Substring(result.IndexOf("Promise<", StringComparison.OrdinalIgnoreCase))); + Assert.DoesNotContain("| undefined", result[result.IndexOf(": Promise<", StringComparison.OrdinalIgnoreCase)..]); AssertExtensions.CurlyBracesAreClosed(result, 1); } From 252425326f8d2f5fbeeef5e021d10ae35798b529 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Fri, 2 Feb 2024 15:01:09 -0500 Subject: [PATCH 21/21] - fixes additional failing unit test Signed-off-by: Vincent Biret --- .../Writers/TypeScript/CodeFunctionWriterTests.cs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tests/Kiota.Builder.Tests/Writers/TypeScript/CodeFunctionWriterTests.cs b/tests/Kiota.Builder.Tests/Writers/TypeScript/CodeFunctionWriterTests.cs index cb9856a699..9ffcb50952 100644 --- a/tests/Kiota.Builder.Tests/Writers/TypeScript/CodeFunctionWriterTests.cs +++ b/tests/Kiota.Builder.Tests/Writers/TypeScript/CodeFunctionWriterTests.cs @@ -715,7 +715,7 @@ public void WritesMethodAsyncDescription() Assert.Contains("@param ", result); Assert.Contains(ParamName, result); Assert.Contains(ParamDescription, result); - Assert.Contains("@returns a Promise of", result); + Assert.Contains("@returns {Promise<", result); Assert.Contains("*/", result); AssertExtensions.CurlyBracesAreClosed(result, 1); } @@ -750,7 +750,7 @@ public void WritesMethodSyncDescription() root.TryAddCodeFile("foo", function); writer.Write(function); var result = tw.ToString(); - Assert.DoesNotContain("@returns a Promise of", result); + Assert.DoesNotContain("@returns {Promise<", result); AssertExtensions.CurlyBracesAreClosed(result, 1); } [Fact]