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 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..5fd6219455 100644 --- a/src/Kiota.Builder/CodeDOM/CodeDocumentation.cs +++ b/src/Kiota.Builder/CodeDOM/CodeDocumentation.cs @@ -1,4 +1,7 @@ using System; +using System.Collections.Concurrent; +using System.Collections.Generic; +using System.Linq; namespace Kiota.Builder.CodeDOM; @@ -7,10 +10,19 @@ 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. /// - public string Description + public string DescriptionTemplate { get; set; } = string.Empty; @@ -34,14 +46,44 @@ 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, string? typeReferencePrefix = null, string? typeReferenceSuffix = null, Func? normalizationFunc = null) + { + 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, Func? normalizationFunc = null) + { + ArgumentNullException.ThrowIfNull(typeReferenceResolver); + if (string.IsNullOrEmpty(descriptionTemplate)) + return string.Empty; + var description = normalizationFunc is null ? descriptionTemplate : normalizationFunc(descriptionTemplate); + if (typeReferences is not null) + foreach (var (key, value) in typeReferences) + { + 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 { - get => !string.IsNullOrEmpty(Description); + get => !string.IsNullOrEmpty(DescriptionTemplate); } public bool ExternalDocumentationAvailable { diff --git a/src/Kiota.Builder/CodeDOM/DeprecationInformation.cs b/src/Kiota.Builder/CodeDOM/DeprecationInformation.cs index 7a06eac09e..08ef9cc452 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, Dictionary? 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/KiotaBuilder.cs b/src/Kiota.Builder/KiotaBuilder.cs index a001466ca7..c381bdd15d 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, @@ -926,9 +926,15 @@ private void CreateUrlManagement(CodeClass currentClass, OpenApiUrlTreeNode curr Kind = isApiClientClass ? CodeMethodKind.ClientConstructor : CodeMethodKind.Constructor, IsAsync = false, IsStatic = false, - Documentation = new() - { - Description = $"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 }, @@ -939,7 +945,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 +994,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 +1019,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 +1130,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 +1159,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 +1195,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", }, @@ -1328,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); @@ -1356,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); } } @@ -1396,7 +1402,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 +1420,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 +1451,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 }, }; @@ -1457,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); } @@ -1471,7 +1477,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 +1520,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 +1558,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 +1569,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 +1579,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 +1619,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 +1636,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 +1663,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 +1676,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 +1721,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) && + !currentClass.Documentation.DescriptionAvailable && 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 +1924,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 +1955,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 +1986,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 +2183,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 +2199,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 +2282,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 +2304,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 +2314,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 +2336,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 +2364,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 +2393,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 +2444,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, @@ -2457,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); diff --git a/src/Kiota.Builder/Refiners/CommonLanguageRefiner.cs b/src/Kiota.Builder/Refiners/CommonLanguageRefiner.cs index 8220666d32..7e142e8c48 100644 --- a/src/Kiota.Builder/Refiners/CommonLanguageRefiner.cs +++ b/src/Kiota.Builder/Refiners/CommonLanguageRefiner.cs @@ -186,9 +186,9 @@ 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)) { - 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, @@ -201,9 +201,9 @@ 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)) { - 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(), @@ -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, + }} + }) { - Description = $"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,9 +486,11 @@ private static CodeType ConvertComposedTypeToWrapper(CodeClass codeClass, CodeCo newClass = @namespace.AddClass(new CodeClass { Name = codeComposedType.Name, - Documentation = new() + Documentation = new(new() { + { "TypesList", codeComposedType } + }) { - Description = description, + DescriptionTemplate = description, }, Deprecation = codeComposedType.Deprecation, }).Last(); @@ -493,9 +500,11 @@ private static CodeType ConvertComposedTypeToWrapper(CodeClass codeClass, CodeCo newClass = targetNamespace.AddClass(new CodeClass { Name = codeComposedType.Name, - Documentation = new() + Documentation = new(new() { + { "TypesList", codeComposedType } + }) { - Description = description + DescriptionTemplate = description }, }) .First(); @@ -513,9 +522,11 @@ private static CodeType ConvertComposedTypeToWrapper(CodeClass codeClass, CodeCo newClass = codeClass.AddInnerClass(new CodeClass { Name = codeComposedType.Name, - Documentation = new() + Documentation = new(new() { + { "TypesList", codeComposedType } + }) { - Description = description + DescriptionTemplate = description }, }) .First(); @@ -526,9 +537,11 @@ private static CodeType ConvertComposedTypeToWrapper(CodeClass codeClass, CodeCo { Name = x.Name, Type = x, - Documentation = new() + Documentation = new(new() { + { "TypeName", x } + }) { - Description = $"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) || @@ -570,7 +583,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 +1337,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 +1352,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 +1504,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 +1520,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..f8830ceeb0 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 => @@ -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 }} + }) { - Description = $"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 } + }) { - Description = $"Instantiates a new {queryParameterProperty.Type.Name}." + DescriptionTemplate = "Instantiates a new {TypeName}." }, 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..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.Description); + 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 f7197d2894..9a965ca619 100644 --- a/src/Kiota.Builder/Writers/CSharp/CSharpConventionService.cs +++ b/src/Kiota.Builder/Writers/CSharp/CSharpConventionService.cs @@ -36,21 +36,37 @@ 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 WriteAdditionalDescriptionItem(string description, LanguageWriter writer) { ArgumentNullException.ThrowIfNull(writer); - if (documentation is null) return; + ArgumentNullException.ThrowIfNull(description); + writer.WriteLine($"{DocCommentPrefix}{description}"); + } + public void WriteLongDescription(IDocumentedElement element, LanguageWriter writer) + { + ArgumentNullException.ThrowIfNull(writer); + 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.Description.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}"); @@ -276,7 +292,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/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 9d5cff7f51..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.Description, 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.Description, 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 1fb64158b2..cde95bac5b 100644 --- a/src/Kiota.Builder/Writers/CSharp/CodeIndexerWriter.cs +++ b/src/Kiota.Builder/Writers/CSharp/CodeIndexerWriter.cs @@ -12,8 +12,9 @@ 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, 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 8ecebe7690..65e75ae003 100644 --- a/src/Kiota.Builder/Writers/CSharp/CodeMethodWriter.cs +++ b/src/Kiota.Builder/Writers/CSharp/CodeMethodWriter.cs @@ -541,13 +541,29 @@ protected string GetSendRequestMethodName(bool isVoid, CodeElement currentElemen } private void WriteMethodDocumentation(CodeMethod code, LanguageWriter writer) { - conventions.WriteLongDescription(code.Documentation, 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)) - writer.WriteLine($"{conventions.DocCommentPrefix}{paramWithDescription.Documentation.Description.CleanupXMLString()}"); + 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/src/Kiota.Builder/Writers/CSharp/CodePropertyWriter.cs b/src/Kiota.Builder/Writers/CSharp/CodePropertyWriter.cs index 48fef8fa98..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.Description, 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 79920c97cb..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($"{className} {currentClass.Documentation.Description.ToFirstCharacterLowerCase()}", writer); + 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/CodeEnumWriter.cs b/src/Kiota.Builder/Writers/Go/CodeEnumWriter.cs index 610d736db6..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.Description, writer); + conventions.WriteShortDescription(codeElement, 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 (item.Documentation.DescriptionAvailable) + writer.WriteLine($"// {item.Documentation.DescriptionTemplate}"); if (isMultiValue) writer.WriteLine($"{item.Name.ToUpperInvariant()}_{typeName.ToUpperInvariant()} = {(int)Math.Pow(2, power)}"); @@ -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(); diff --git a/src/Kiota.Builder/Writers/Go/CodeInterfaceDeclarationWriter.cs b/src/Kiota.Builder/Writers/Go/CodeInterfaceDeclarationWriter.cs index d6a31487db..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.Description.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 9274be5c87..16b4a4fc44 100644 --- a/src/Kiota.Builder/Writers/Go/CodeMethodWriter.cs +++ b/src/Kiota.Builder/Writers/Go/CodeMethodWriter.cs @@ -290,11 +290,30 @@ 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(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/CodePropertyWriter.cs b/src/Kiota.Builder/Writers/Go/CodePropertyWriter.cs index a139c2447e..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.Description, 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 559c0e5876..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); @@ -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, true, false)); + 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.Description}{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 f643363124..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.Description, 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 55c24cb677..c542d9ca51 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; @@ -736,17 +737,34 @@ 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} {JavaConventionService.RemoveInvalidDescriptionCharacters(x.Documentation.Description)}") - .Union(new[] { returnRemark })); + .Select(x => $"@param {x.Name} {x.Documentation.GetDescription(y => conventions.GetTypeReferenceForDocComment(y, code), normalizationFunc: JavaConventionService.RemoveInvalidDescriptionCharacters)}") + .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/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 7d7d749cad..314a0404a5 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,25 +92,45 @@ _ 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) + 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 = "") { 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 => 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 = Enumerable.Empty(); - var remarks = additionalRemarks.ToArray(); + additionalRemarks = []; + var remarks = additionalRemarks.Where(static x => !string.IsNullOrEmpty(x)).ToArray(); if (documentation.DescriptionAvailable || documentation.ExternalDocumentationAvailable || remarks.Length != 0) { writer.WriteLine(DocCommentStart); if (documentation.DescriptionAvailable) - writer.WriteLine($"{DocCommentPrefix}{RemoveInvalidDescriptionCharacters(documentation.Description)}"); - foreach (var additionalRemark in remarks.Where(static x => !string.IsNullOrEmpty(x))) + { + var description = documentedElement.Documentation.GetDescription(x => GetTypeReferenceForDocComment(x, element), ReferenceTypePrefix, ReferenceTypeSuffix, RemoveInvalidDescriptionCharacters); + writer.WriteLine($"{DocCommentPrefix}{description}"); + } + 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)) @@ -160,10 +179,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/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 8172fcbcbe..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.Description; + 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.Description}"; + return $"@param array $value {x?.Documentation.GetDescription(x => conventions.GetTypeString(x, codeMethod), normalizationFunc: PhpConventionService.RemoveInvalidDescriptionCharacters)}"; } - return $"@param {conventions.GetParameterDocNullable(x, x)} {x?.Documentation.Description}"; + 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 bc68cd145e..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.Description; + 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.Description, 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 cf02f48669..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.Description)}"); + 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 89eea849dd..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.Description, 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 39af4fe555..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.Description, 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.Description, 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.Description, 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.Description)}") - .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 0605377453..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.Description, 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 caa6829fd6..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.Description)}"); + { + 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) @@ -201,7 +209,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/Ruby/CodeClassDeclarationWriter.cs b/src/Kiota.Builder/Writers/Ruby/CodeClassDeclarationWriter.cs index 4f4d6947a4..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.Description, 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 daaa9f5699..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.Description, 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 d80ae29ec3..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.Description); - var parametersWithDescription = code.Parameters.Where(x => !string.IsNullOrEmpty(code.Documentation.Description)).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.Description)}"); + 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.Description)}"); + { + 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 f4e2bd074d..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.Description, 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 ae106e1cfd..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.Description, 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 f18517501a..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.Description, 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 f90f287497..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,16 +35,31 @@ 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, code.Parameters .Where(static x => x.Documentation.DescriptionAvailable) .OrderBy(static x => x.Name) - .Select(x => $"@param {x.Name} {TypeScriptConventionService.RemoveInvalidDescriptionCharacters(x.Documentation.Description)}") - .Union(new[] { returnRemark })); + .Select(x => $"@param {x.Name} {x.Documentation.GetDescription(type => typeScriptConventionService.GetTypeString(type, code), TypeScriptConventionService.ReferenceTypePrefix, TypeScriptConventionService.ReferenceTypeSuffix, TypeScriptConventionService.RemoveInvalidDescriptionCharacters)}") + .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) diff --git a/src/Kiota.Builder/Writers/TypeScript/TypeScriptConventionService.cs b/src/Kiota.Builder/Writers/TypeScript/TypeScriptConventionService.cs index 0c0901e5f4..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.Description)}"); + { + 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}"); @@ -169,6 +178,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/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/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); } } 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..a55e1d7e63 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" } } }; @@ -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); } } diff --git a/tests/Kiota.Builder.Tests/Writers/CSharp/CodeMethodWriterTests.cs b/tests/Kiota.Builder.Tests/Writers/CSharp/CodeMethodWriterTests.cs index 341ce241d3..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("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..9ffcb50952 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 @@ -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); } @@ -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 @@ -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] @@ -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 @@ -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); }