From e93db3b481176406291b592d666c4f6f2c17c394 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Wed, 7 Dec 2022 09:59:28 -0500 Subject: [PATCH 01/12] - adds a structure to hold the documentation link Signed-off-by: Vincent Biret --- .../CodeDOM/CodeDocumentation.cs | 42 +++++++++++++++++++ src/Kiota.Builder/CodeDOM/CodeEnum.cs | 3 +- src/Kiota.Builder/CodeDOM/CodeEnumOption.cs | 3 +- src/Kiota.Builder/CodeDOM/CodeIndexer.cs | 3 +- src/Kiota.Builder/CodeDOM/CodeMethod.cs | 4 +- src/Kiota.Builder/CodeDOM/CodeParameter.cs | 3 +- src/Kiota.Builder/CodeDOM/CodeProperty.cs | 3 +- .../CodeDOM/IDocumentedElement.cs | 11 +++-- .../CodeDOM/ProprietableBlock.cs | 3 +- src/Kiota.Builder/KiotaBuilder.cs | 6 ++- 10 files changed, 69 insertions(+), 12 deletions(-) create mode 100644 src/Kiota.Builder/CodeDOM/CodeDocumentation.cs diff --git a/src/Kiota.Builder/CodeDOM/CodeDocumentation.cs b/src/Kiota.Builder/CodeDOM/CodeDocumentation.cs new file mode 100644 index 0000000000..374472e268 --- /dev/null +++ b/src/Kiota.Builder/CodeDOM/CodeDocumentation.cs @@ -0,0 +1,42 @@ + +using System; + +namespace Kiota.Builder.CodeDOM; + +/// +/// The documentation information of a code element. +/// +public class CodeDocumentation : ICloneable +{ + /// + /// The description of the current element. + /// + public string Description + { + get; set; + } + /// + /// The external documentation link for this method. + /// + public Uri DocumentationLink + { + get; set; + } + /// + ///The label for the external documentation link. + /// + public string DocumentationLabel + { + get; set; + } + + /// + public object Clone() + { + return new CodeDocumentation { + Description = Description?.Clone() as string, + DocumentationLink = DocumentationLink == null ? null : new (DocumentationLink.ToString()), + DocumentationLabel = DocumentationLabel?.Clone() as string, + }; + } +} diff --git a/src/Kiota.Builder/CodeDOM/CodeEnum.cs b/src/Kiota.Builder/CodeDOM/CodeEnum.cs index d0e678293b..0ed1cb7e73 100644 --- a/src/Kiota.Builder/CodeDOM/CodeEnum.cs +++ b/src/Kiota.Builder/CodeDOM/CodeEnum.cs @@ -7,7 +7,8 @@ public class CodeEnum : CodeBlock, IDocumentedElemen private readonly HashSet optionsNames = new(StringComparer.OrdinalIgnoreCase); // this structure is used to check if an option name is unique private readonly ConcurrentQueue OptionsInternal = new (); // this structure is used to maintain the order of the options public bool Flags { get; set; } - public string Description {get; set;} + public string Description { get => Documentation.Description; set => Documentation.Description = value; } + public CodeDocumentation Documentation { get; set; } = new(); public void AddOption(params CodeEnumOption[] codeEnumOptions) { diff --git a/src/Kiota.Builder/CodeDOM/CodeEnumOption.cs b/src/Kiota.Builder/CodeDOM/CodeEnumOption.cs index bd6ef30c68..6e3e510b84 100644 --- a/src/Kiota.Builder/CodeDOM/CodeEnumOption.cs +++ b/src/Kiota.Builder/CodeDOM/CodeEnumOption.cs @@ -3,7 +3,8 @@ namespace Kiota.Builder.CodeDOM; public class CodeEnumOption : IDocumentedElement, ITypeDefinition { public string SerializationName { get; set; } - public string Description { get; set; } + public string Description { get => Documentation.Description; set => Documentation.Description = value; } + public CodeDocumentation Documentation { get; set; } = new(); public string Name { get; set; } public CodeElement Parent { get; set; } } diff --git a/src/Kiota.Builder/CodeDOM/CodeIndexer.cs b/src/Kiota.Builder/CodeDOM/CodeIndexer.cs index dfdfff02f5..04892221cb 100644 --- a/src/Kiota.Builder/CodeDOM/CodeIndexer.cs +++ b/src/Kiota.Builder/CodeDOM/CodeIndexer.cs @@ -12,7 +12,8 @@ public class CodeIndexer : CodeTerminal, IDocumentedElement returnType = value; }} public string SerializationName { get; set; } - public string Description {get; set;} + public string Description { get => Documentation.Description; set => Documentation.Description = value; } + public CodeDocumentation Documentation { get; set; } = new(); /// /// The Path segment to use for the method name when using back-compatible methods. /// diff --git a/src/Kiota.Builder/CodeDOM/CodeMethod.cs b/src/Kiota.Builder/CodeDOM/CodeMethod.cs index 6a01a63a0a..47e1bd78fb 100644 --- a/src/Kiota.Builder/CodeDOM/CodeMethod.cs +++ b/src/Kiota.Builder/CodeDOM/CodeMethod.cs @@ -141,7 +141,8 @@ public void ClearParameters() public IEnumerable Parameters { get => parameters.Values.OrderBy(static x => x, parameterOrderComparer); } public bool IsStatic {get;set;} public bool IsAsync {get;set;} = true; - public string Description {get; set;} + public string Description { get => Documentation.Description; set => Documentation.Description = value; } + public CodeDocumentation Documentation { get; set; } = new(); public PagingInformation PagingInformation { @@ -244,6 +245,7 @@ public object Clone() errorMappings = errorMappings == null ? null : new (errorMappings), acceptedResponseTypes = acceptedResponseTypes == null ? null : new (acceptedResponseTypes), PagingInformation = PagingInformation?.Clone() as PagingInformation, + Documentation = Documentation?.Clone() as CodeDocumentation, }; if(Parameters?.Any() ?? false) method.AddParameter(Parameters.Select(x => x.Clone() as CodeParameter).ToArray()); diff --git a/src/Kiota.Builder/CodeDOM/CodeParameter.cs b/src/Kiota.Builder/CodeDOM/CodeParameter.cs index 10ef16a5c0..8bcb934cfa 100644 --- a/src/Kiota.Builder/CodeDOM/CodeParameter.cs +++ b/src/Kiota.Builder/CodeDOM/CodeParameter.cs @@ -57,7 +57,8 @@ public class CodeParameter : CodeTerminalWithKind, ICloneable type = value; }} public bool Optional {get;set;} - public string Description {get; set;} + public string Description { get => Documentation.Description; set => Documentation.Description = value; } + public CodeDocumentation Documentation { get; set; } = new(); public string DefaultValue {get; set;} public string SerializationName { get; set; } public object Clone() diff --git a/src/Kiota.Builder/CodeDOM/CodeProperty.cs b/src/Kiota.Builder/CodeDOM/CodeProperty.cs index 6ff4197381..99c5494117 100644 --- a/src/Kiota.Builder/CodeDOM/CodeProperty.cs +++ b/src/Kiota.Builder/CodeDOM/CodeProperty.cs @@ -72,7 +72,8 @@ public CodeMethod SetterFromCurrentOrBaseType { type = value; }} public string DefaultValue {get;set;} - public string Description {get; set;} + public string Description { get => Documentation.Description; set => Documentation.Description = value; } + public CodeDocumentation Documentation { get; set; } = new(); public string SerializationName { get; set; } public string NamePrefix { get; set; } public bool IsNameEscaped { get => !string.IsNullOrEmpty(SerializationName); } diff --git a/src/Kiota.Builder/CodeDOM/IDocumentedElement.cs b/src/Kiota.Builder/CodeDOM/IDocumentedElement.cs index 67fc2cc75a..258a8c41d6 100644 --- a/src/Kiota.Builder/CodeDOM/IDocumentedElement.cs +++ b/src/Kiota.Builder/CodeDOM/IDocumentedElement.cs @@ -1,5 +1,8 @@ -namespace Kiota.Builder.CodeDOM { - public interface IDocumentedElement { - string Description {get; set;} - } +using System; + +namespace Kiota.Builder.CodeDOM; +public interface IDocumentedElement { + [Obsolete("Use the Documentation property instead.")] + string Description {get; set;} + CodeDocumentation Documentation {get; set;} } diff --git a/src/Kiota.Builder/CodeDOM/ProprietableBlock.cs b/src/Kiota.Builder/CodeDOM/ProprietableBlock.cs index 159afe736a..28a766bf2f 100644 --- a/src/Kiota.Builder/CodeDOM/ProprietableBlock.cs +++ b/src/Kiota.Builder/CodeDOM/ProprietableBlock.cs @@ -28,7 +28,8 @@ public override string Name StartBlock.Name = name; } } - public string Description {get; set;} + public string Description { get => Documentation.Description; set => Documentation.Description = value; } + public CodeDocumentation Documentation { get; set; } = new(); public virtual IEnumerable AddProperty(params CodeProperty[] properties) { if(properties == null || properties.Any(x => x == null)) diff --git a/src/Kiota.Builder/KiotaBuilder.cs b/src/Kiota.Builder/KiotaBuilder.cs index 2e5b6c0417..0f322c9fb5 100644 --- a/src/Kiota.Builder/KiotaBuilder.cs +++ b/src/Kiota.Builder/KiotaBuilder.cs @@ -800,8 +800,12 @@ private void CreateOperationMethods(OpenApiUrlTreeNode currentNode, OperationTyp Name = operationType.ToString(), Kind = CodeMethodKind.RequestExecutor, HttpMethod = method, - Description = (operation.Description ?? operation.Summary).CleanupDescription(), Parent = parentClass, + Documentation = new () { + DocumentationLink = operation.ExternalDocs?.Url, + DocumentationLabel = operation.ExternalDocs?.Description, + Description = (operation.Description ?? operation.Summary).CleanupDescription(), + } }; if (operation.Extensions.TryGetValue(OpenApiPagingExtension.Name, out var extension) && extension is OpenApiPagingExtension pagingExtension) From 42e03bb3ae33b678076be38db6d32eb10bd32cce Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Wed, 7 Dec 2022 11:20:31 -0500 Subject: [PATCH 02/12] - refactors description model design --- src/Kiota.Builder/CodeDOM/CodeEnum.cs | 1 - src/Kiota.Builder/CodeDOM/CodeEnumOption.cs | 1 - src/Kiota.Builder/CodeDOM/CodeIndexer.cs | 1 - src/Kiota.Builder/CodeDOM/CodeMethod.cs | 10 +- src/Kiota.Builder/CodeDOM/CodeParameter.cs | 3 +- src/Kiota.Builder/CodeDOM/CodeProperty.cs | 1 - .../CodeDOM/IDocumentedElement.cs | 4 - .../CodeDOM/ProprietableBlock.cs | 1 - src/Kiota.Builder/KiotaBuilder.cs | 148 +++++++++++++----- .../Refiners/CommonLanguageRefiner.cs | 50 ++++-- src/Kiota.Builder/Refiners/GoRefiner.cs | 8 +- src/Kiota.Builder/Refiners/JavaRefiner.cs | 4 +- src/Kiota.Builder/Refiners/PythonRefiner.cs | 2 +- src/Kiota.Builder/Refiners/ShellRefiner.cs | 21 ++- src/Kiota.Builder/Refiners/SwiftRefiner.cs | 4 +- .../Refiners/TypeScriptRefiner.cs | 2 +- .../CSharp/CodeClassDeclarationWriter.cs | 2 +- .../Writers/CSharp/CodeEnumWriter.cs | 4 +- .../Writers/CSharp/CodeIndexerWriter.cs | 2 +- .../Writers/CSharp/CodeMethodWriter.cs | 8 +- .../Writers/CSharp/CodePropertyWriter.cs | 2 +- .../Writers/Go/CodeClassDeclarationWriter.cs | 2 +- .../Writers/Go/CodeEnumWriter.cs | 6 +- .../Go/CodeInterfaceDeclarationWriter.cs | 2 +- .../Writers/Go/CodeMethodWriter.cs | 4 +- .../Writers/Go/CodePropertyWriter.cs | 2 +- .../Java/CodeClassDeclarationWriter.cs | 2 +- .../Writers/Java/CodeEnumWriter.cs | 4 +- .../Writers/Java/CodeMethodWriter.cs | 8 +- .../Writers/Java/CodePropertyWriter.cs | 2 +- .../Writers/Php/CodeMethodWriter.cs | 6 +- .../Writers/Php/CodePropertyWriter.cs | 4 +- .../Python/CodeClassDeclarationWriter.cs | 2 +- .../Writers/Python/CodeEnumWriter.cs | 2 +- .../Writers/Python/CodeMethodWriter.cs | 12 +- .../Writers/Python/CodePropertyWriter.cs | 4 +- .../Ruby/CodeClassDeclarationWriter.cs | 2 +- .../Writers/Ruby/CodeEnumWriter.cs | 2 +- .../Writers/Ruby/CodeMethodWriter.cs | 12 +- .../Writers/Ruby/CodePropertyWriter.cs | 2 +- .../Writers/Shell/ShellCodeMethodWriter.cs | 8 +- .../Swift/CodeClassDeclarationWriter.cs | 2 +- .../TypeScript/CodeClassDeclarationWriter.cs | 2 +- .../Writers/TypeScript/CodeEnumWriter.cs | 4 +- .../Writers/TypeScript/CodeMethodWriter.cs | 8 +- .../Writers/TypeScript/CodePropertyWriter.cs | 2 +- .../CodeDOM/CodeEnumTests.cs | 4 +- .../CodeDOM/CodeIndexerTests.cs | 26 +-- .../Kiota.Builder.Tests/KiotaBuilderTests.cs | 12 +- .../Refiners/CSharpLanguageRefinerTests.cs | 4 +- .../Refiners/GoLanguageRefinerTests.cs | 4 +- .../Refiners/JavaLanguageRefinerTests.cs | 4 +- .../Refiners/PythonLanguageRefinerTests.cs | 4 +- .../Refiners/RubyLanguageRefinerTests.cs | 4 +- .../TypeScriptLanguageRefinerTests.cs | 4 +- .../Writers/CSharp/CodeEnumWriterTests.cs | 4 +- .../Writers/CSharp/CodeMethodWriterTests.cs | 36 +++-- .../Writers/Go/CodeEnumWriterTests.cs | 6 +- .../Writers/Go/CodeMethodWriterTests.cs | 8 +- .../Writers/Java/CodeEnumWriterTests.cs | 6 +- .../Writers/Java/CodeMethodWriterTests.cs | 36 +++-- .../Writers/Php/CodeMethodWriterTests.cs | 78 ++++++--- .../Writers/Php/CodePropertyWriterTests.cs | 14 +- .../Writers/Python/CodeMethodWriterTests.cs | 48 ++++-- .../Writers/Python/CodePropertyWriterTests.cs | 2 +- .../Writers/Ruby/CodeMethodWriterTests.cs | 32 ++-- .../Shell/ShellCodeMethodWriterTests.cs | 14 +- .../Writers/TypeScript/CodeEnumWriterTests.cs | 6 +- .../TypeScript/CodeMethodWriterTests.cs | 36 +++-- 69 files changed, 483 insertions(+), 294 deletions(-) diff --git a/src/Kiota.Builder/CodeDOM/CodeEnum.cs b/src/Kiota.Builder/CodeDOM/CodeEnum.cs index 0ed1cb7e73..b6b802cfcb 100644 --- a/src/Kiota.Builder/CodeDOM/CodeEnum.cs +++ b/src/Kiota.Builder/CodeDOM/CodeEnum.cs @@ -7,7 +7,6 @@ public class CodeEnum : CodeBlock, IDocumentedElemen private readonly HashSet optionsNames = new(StringComparer.OrdinalIgnoreCase); // this structure is used to check if an option name is unique private readonly ConcurrentQueue OptionsInternal = new (); // this structure is used to maintain the order of the options public bool Flags { get; set; } - public string Description { get => Documentation.Description; set => Documentation.Description = value; } public CodeDocumentation Documentation { get; set; } = new(); public void AddOption(params CodeEnumOption[] codeEnumOptions) diff --git a/src/Kiota.Builder/CodeDOM/CodeEnumOption.cs b/src/Kiota.Builder/CodeDOM/CodeEnumOption.cs index 6e3e510b84..cc6dbd7948 100644 --- a/src/Kiota.Builder/CodeDOM/CodeEnumOption.cs +++ b/src/Kiota.Builder/CodeDOM/CodeEnumOption.cs @@ -3,7 +3,6 @@ namespace Kiota.Builder.CodeDOM; public class CodeEnumOption : IDocumentedElement, ITypeDefinition { public string SerializationName { get; set; } - public string Description { get => Documentation.Description; set => Documentation.Description = value; } public CodeDocumentation Documentation { get; set; } = new(); public string Name { get; set; } public CodeElement Parent { get; set; } diff --git a/src/Kiota.Builder/CodeDOM/CodeIndexer.cs b/src/Kiota.Builder/CodeDOM/CodeIndexer.cs index 04892221cb..834e458d70 100644 --- a/src/Kiota.Builder/CodeDOM/CodeIndexer.cs +++ b/src/Kiota.Builder/CodeDOM/CodeIndexer.cs @@ -12,7 +12,6 @@ public class CodeIndexer : CodeTerminal, IDocumentedElement returnType = value; }} public string SerializationName { get; set; } - public string Description { get => Documentation.Description; set => Documentation.Description = value; } public CodeDocumentation Documentation { get; set; } = new(); /// /// The Path segment to use for the method name when using back-compatible methods. diff --git a/src/Kiota.Builder/CodeDOM/CodeMethod.cs b/src/Kiota.Builder/CodeDOM/CodeMethod.cs index 47e1bd78fb..43dc6f5165 100644 --- a/src/Kiota.Builder/CodeDOM/CodeMethod.cs +++ b/src/Kiota.Builder/CodeDOM/CodeMethod.cs @@ -82,7 +82,9 @@ public static CodeMethod FromIndexer(CodeIndexer originalIndexer, CodeClass inde Access = AccessModifier.Public, Kind = CodeMethodKind.IndexerBackwardCompatibility, Name = originalIndexer.PathSegment + methodNameSuffix, - Description = originalIndexer.Description, + Documentation = new () { + Description = originalIndexer.Documentation.Description, + }, ReturnType = new CodeType { IsNullable = false, TypeDefinition = indexerClass, @@ -94,7 +96,9 @@ public static CodeMethod FromIndexer(CodeIndexer originalIndexer, CodeClass inde Name = "id", Optional = false, Kind = CodeParameterKind.Custom, - Description = "Unique identifier of the item", + Documentation = new() { + Description = "Unique identifier of the item", + }, Type = new CodeType { Name = "String", IsNullable = parameterNullable, @@ -141,7 +145,6 @@ public void ClearParameters() public IEnumerable Parameters { get => parameters.Values.OrderBy(static x => x, parameterOrderComparer); } public bool IsStatic {get;set;} public bool IsAsync {get;set;} = true; - public string Description { get => Documentation.Description; set => Documentation.Description = value; } public CodeDocumentation Documentation { get; set; } = new(); public PagingInformation PagingInformation @@ -233,7 +236,6 @@ public object Clone() IsAsync = IsAsync, Access = Access, IsStatic = IsStatic, - Description = Description?.Clone() as string, RequestBodyContentType = RequestBodyContentType?.Clone() as string, BaseUrl = BaseUrl?.Clone() as string, AccessedProperty = AccessedProperty, diff --git a/src/Kiota.Builder/CodeDOM/CodeParameter.cs b/src/Kiota.Builder/CodeDOM/CodeParameter.cs index 8bcb934cfa..1d78aa4d6b 100644 --- a/src/Kiota.Builder/CodeDOM/CodeParameter.cs +++ b/src/Kiota.Builder/CodeDOM/CodeParameter.cs @@ -57,7 +57,6 @@ public class CodeParameter : CodeTerminalWithKind, ICloneable type = value; }} public bool Optional {get;set;} - public string Description { get => Documentation.Description; set => Documentation.Description = value; } public CodeDocumentation Documentation { get; set; } = new(); public string DefaultValue {get; set;} public string SerializationName { get; set; } @@ -68,10 +67,10 @@ public object Clone() Kind = Kind, Name = Name.Clone() as string, Type = Type?.Clone() as CodeTypeBase, - Description = Description?.Clone() as string, DefaultValue = DefaultValue?.Clone() as string, Parent = Parent, SerializationName = SerializationName?.Clone() as string, + Documentation = Documentation?.Clone() as CodeDocumentation, }; } } diff --git a/src/Kiota.Builder/CodeDOM/CodeProperty.cs b/src/Kiota.Builder/CodeDOM/CodeProperty.cs index 99c5494117..f7f346c936 100644 --- a/src/Kiota.Builder/CodeDOM/CodeProperty.cs +++ b/src/Kiota.Builder/CodeDOM/CodeProperty.cs @@ -72,7 +72,6 @@ public CodeMethod SetterFromCurrentOrBaseType { type = value; }} public string DefaultValue {get;set;} - public string Description { get => Documentation.Description; set => Documentation.Description = value; } public CodeDocumentation Documentation { get; set; } = new(); public string SerializationName { get; set; } public string NamePrefix { get; set; } diff --git a/src/Kiota.Builder/CodeDOM/IDocumentedElement.cs b/src/Kiota.Builder/CodeDOM/IDocumentedElement.cs index 258a8c41d6..e49efcea27 100644 --- a/src/Kiota.Builder/CodeDOM/IDocumentedElement.cs +++ b/src/Kiota.Builder/CodeDOM/IDocumentedElement.cs @@ -1,8 +1,4 @@ -using System; - namespace Kiota.Builder.CodeDOM; public interface IDocumentedElement { - [Obsolete("Use the Documentation property instead.")] - string Description {get; set;} CodeDocumentation Documentation {get; set;} } diff --git a/src/Kiota.Builder/CodeDOM/ProprietableBlock.cs b/src/Kiota.Builder/CodeDOM/ProprietableBlock.cs index 28a766bf2f..b4c9da8dd4 100644 --- a/src/Kiota.Builder/CodeDOM/ProprietableBlock.cs +++ b/src/Kiota.Builder/CodeDOM/ProprietableBlock.cs @@ -28,7 +28,6 @@ public override string Name StartBlock.Name = name; } } - public string Description { get => Documentation.Description; set => Documentation.Description = value; } public CodeDocumentation Documentation { get; set; } = new(); public virtual IEnumerable AddProperty(params CodeProperty[] properties) { diff --git a/src/Kiota.Builder/KiotaBuilder.cs b/src/Kiota.Builder/KiotaBuilder.cs index 0f322c9fb5..be45d715a5 100644 --- a/src/Kiota.Builder/KiotaBuilder.cs +++ b/src/Kiota.Builder/KiotaBuilder.cs @@ -423,7 +423,9 @@ private void CreateRequestBuilderClass(CodeNamespace currentNamespace, OpenApiUr codeClass = currentNamespace.AddClass(new CodeClass { Name = config.ClientClassName, Kind = CodeClassKind.RequestBuilder, - Description = "The main entry point of the SDK, exposes the configuration and the fluent API." + Documentation = new() { + Description = "The main entry point of the SDK, exposes the configuration and the fluent API." + }, }).First(); else { @@ -432,7 +434,9 @@ private void CreateRequestBuilderClass(CodeNamespace currentNamespace, OpenApiUr codeClass = targetNS.AddClass(new CodeClass { Name = className.CleanupSymbolName(), Kind = CodeClassKind.RequestBuilder, - Description = currentNode.GetPathItemDescription(Constants.DefaultOpenApiLabel, $"Builds and executes requests for operations under {currentNode.Path}"), + Documentation = new() { + Description = currentNode.GetPathItemDescription(Constants.DefaultOpenApiLabel, $"Builds and executes requests for operations under {currentNode.Path}"), + }, }).First(); } @@ -458,7 +462,7 @@ private void CreateRequestBuilderClass(CodeNamespace currentNamespace, OpenApiUr var prop = CreateProperty(propIdentifier, propType, kind: CodePropertyKind.RequestBuilder); // we should add the type definition here but we can't as it might not have been generated yet if (!string.IsNullOrWhiteSpace(description)) { - prop.Description = description; + prop.Documentation.Description = description; } codeClass.AddProperty(prop); } @@ -487,7 +491,9 @@ private static void CreateMethod(string propIdentifier, string propType, CodeCla { Name = propIdentifier.CleanupSymbolName(), Kind = CodeMethodKind.RequestBuilderWithParameters, - Description = currentNode.GetPathItemDescription(Constants.DefaultOpenApiLabel, $"Builds and executes requests for operations under {currentNode.Path}"), + Documentation = new() { + Description = currentNode.GetPathItemDescription(Constants.DefaultOpenApiLabel, $"Builds and executes requests for operations under {currentNode.Path}"), + }, Access = AccessModifier.Public, IsAsync = false, IsStatic = false, @@ -510,7 +516,9 @@ private static void AddPathParametersToMethod(OpenApiUrlTreeNode currentNode, Co var mParameter = new CodeParameter { Name = codeName, Optional = asOptional, - Description = parameter.Description.CleanupDescription(), + Documentation = new() { + Description = parameter.Description.CleanupDescription(), + }, Kind = CodeParameterKind.Path, SerializationName = parameter.Name.Equals(codeName) ? default : parameter.Name.SanitizeParameterNameForUrlTemplate(), }; @@ -527,7 +535,9 @@ private void CreateUrlManagement(CodeClass currentClass, OpenApiUrlTreeNode curr Name = "urlTemplate", DefaultValue = $"\"{currentNode.GetUrlTemplate()}\"", ReadOnly = true, - Description = "Url template to use to build the URL for the current request builder", + Documentation = new() { + Description = "Url template to use to build the URL for the current request builder", + }, Kind = CodePropertyKind.UrlTemplate, Type = new CodeType { Name = "string", @@ -540,7 +550,9 @@ private void CreateUrlManagement(CodeClass currentClass, OpenApiUrlTreeNode curr var requestAdapterProperty = new CodeProperty { Name = requestAdapterParameterName, - Description = "The request adapter to use to execute the requests.", + Documentation = new() { + Description = "The request adapter to use to execute the requests.", + }, Kind = CodePropertyKind.RequestAdapter, Access = AccessModifier.Private, ReadOnly = true, @@ -557,14 +569,18 @@ private void CreateUrlManagement(CodeClass currentClass, OpenApiUrlTreeNode curr Kind = isApiClientClass ? CodeMethodKind.ClientConstructor : CodeMethodKind.Constructor, IsAsync = false, IsStatic = false, - Description = $"Instantiates a new {currentClass.Name.ToFirstCharacterUpperCase()} and sets the default values.", + Documentation = new() { + Description = $"Instantiates a new {currentClass.Name.ToFirstCharacterUpperCase()} and sets the default values.", + }, Access = AccessModifier.Public, ReturnType = new CodeType { Name = voidType, IsExternal = true }, Parent = currentClass, }; var pathParametersProperty = new CodeProperty { Name = PathParametersParameterName, - Description = "Path parameters for the request", + Documentation = new() { + Description = "Path parameters for the request", + }, Kind = CodePropertyKind.PathParameters, Access = AccessModifier.Private, ReadOnly = true, @@ -585,7 +601,7 @@ private void CreateUrlManagement(CodeClass currentClass, OpenApiUrlTreeNode curr Name = PathParametersParameterName, Type = pathParametersProperty.Type, Optional = false, - Description = pathParametersProperty.Description, + Documentation = pathParametersProperty.Documentation.Clone() as CodeDocumentation, Kind = CodeParameterKind.PathParameters, }); AddPathParametersToMethod(currentNode, constructor, true); @@ -594,7 +610,7 @@ private void CreateUrlManagement(CodeClass currentClass, OpenApiUrlTreeNode curr Name = requestAdapterParameterName, Type = requestAdapterProperty.Type, Optional = false, - Description = requestAdapterProperty.Description, + Documentation = requestAdapterProperty.Documentation.Clone() as CodeDocumentation, Kind = CodeParameterKind.RequestAdapter, }); if(isApiClientClass && config.UsesBackingStore) { @@ -602,7 +618,9 @@ private void CreateUrlManagement(CodeClass currentClass, OpenApiUrlTreeNode curr var backingStoreParam = new CodeParameter { Name = "backingStore", Optional = true, - Description = "The backing store to use for the models.", + Documentation = new() { + Description = "The backing store to use for the models.", + }, Kind = CodeParameterKind.BackingStore, Type = new CodeType { Name = factoryInterfaceName, @@ -682,7 +700,9 @@ private CodeIndexer CreateIndexer(string childIdentifier, string childType, Open return new CodeIndexer { Name = childIdentifier, - Description = currentNode.GetPathItemDescription(Constants.DefaultOpenApiLabel, $"Gets an item from the {currentNode.GetNodeNamespaceFromPath(config.ClientNamespaceName)} collection"), + Documentation = new() { + Description = currentNode.GetPathItemDescription(Constants.DefaultOpenApiLabel, $"Gets an item from the {currentNode.GetNodeNamespaceFromPath(config.ClientNamespaceName)} collection"), + }, IndexType = new CodeType { Name = "string", IsExternal = true, }, ReturnType = new CodeType { Name = childType }, SerializationName = currentNode.Segment.SanitizeParameterNameForUrlTemplate(), @@ -697,7 +717,9 @@ private CodeProperty CreateProperty(string childIdentifier, string childType, Op { Name = propertyName, Kind = kind, - Description = typeSchema?.Description.CleanupDescription() ?? $"The {propertyName} property", + Documentation = new() { + Description = typeSchema?.Description.CleanupDescription() ?? $"The {propertyName} property", + }, ReadOnly = typeSchema?.ReadOnly ?? false, }; if(propertyName != childIdentifier) @@ -791,7 +813,9 @@ private void CreateOperationMethods(OpenApiUrlTreeNode currentNode, OperationTyp var requestConfigClass = parentClass.AddInnerClass(new CodeClass { Name = $"{parentClass.Name}{operationType}RequestConfiguration", Kind = CodeClassKind.RequestConfiguration, - Description = "Configuration for the request such as headers, query parameters, and middleware options.", + Documentation = new() { + Description = "Configuration for the request such as headers, query parameters, and middleware options.", + }, }).First(); var schema = operation.GetResponseSchema(config.StructuredMimeTypes); @@ -842,7 +866,9 @@ private void CreateOperationMethods(OpenApiUrlTreeNode currentNode, OperationTyp Name = "responseHandler", Optional = true, Kind = CodeParameterKind.ResponseHandler, - Description = "Response handler to use in place of the default response handling provided by the core service", + Documentation = new() { + Description = "Response handler to use in place of the default response handling provided by the core service", + }, Type = new CodeType { Name = "IResponseHandler", IsExternal = true }, }; executorMethod.AddParameter(handlerParam);// Add response handler parameter @@ -851,7 +877,9 @@ private void CreateOperationMethods(OpenApiUrlTreeNode currentNode, OperationTyp Name = "cancellationToken", Optional = true, Kind = CodeParameterKind.Cancellation, - Description = "Cancellation token to use when cancelling requests", + Documentation = new() { + Description = "Cancellation token to use when cancelling requests", + }, Type = new CodeType { Name = "CancellationToken", IsExternal = true }, }; executorMethod.AddParameter(cancellationParam);// Add cancellation token parameter @@ -862,7 +890,9 @@ private void CreateOperationMethods(OpenApiUrlTreeNode currentNode, OperationTyp Kind = CodeMethodKind.RequestGenerator, IsAsync = false, HttpMethod = method, - Description = (operation.Description ?? operation.Summary).CleanupDescription(), + Documentation = new() { + Description = (operation.Description ?? operation.Summary).CleanupDescription(), + }, ReturnType = new CodeType { Name = "RequestInformation", IsNullable = false, IsExternal = true}, Parent = parentClass, }; @@ -883,7 +913,9 @@ private void CreateOperationMethods(OpenApiUrlTreeNode currentNode, OperationTyp Name = codeName, SerializationName = codeName.Equals(x.Name) ? default : x.Name, Type = GetQueryParameterType(x.Schema), - Description = x.Description.CleanupDescription(), + Documentation = new() { + Description = x.Description.CleanupDescription(), + }, Kind = x.In switch { ParameterLocation.Query => CodeParameterKind.QueryParameter, @@ -916,20 +948,26 @@ private static void AddRequestConfigurationProperties(CodeClass parameterClass, { Name = "queryParameters", Kind = CodePropertyKind.QueryParameters, - Description = "Request query parameters", + Documentation = new() { + Description = "Request query parameters", + }, Type = new CodeType { Name = parameterClass.Name, TypeDefinition = parameterClass }, }); } requestConfigClass.AddProperty(new CodeProperty { Name = "headers", Kind = CodePropertyKind.Headers, - Description = "Request headers", + Documentation = new() { + Description = "Request headers", + }, Type = new CodeType { Name = "IDictionary", IsExternal = true }, }, new CodeProperty { Name = "options", Kind = CodePropertyKind.Options, - Description = "Request options", + Documentation = new() { + Description = "Request options", + }, Type = new CodeType { Name = "IList", IsExternal = true }, }); } @@ -943,7 +981,9 @@ private void AddRequestBuilderMethodParameters(OpenApiUrlTreeNode currentNode, O Type = requestBodyType, Optional = false, Kind = CodeParameterKind.RequestBody, - Description = requestBodySchema.Description.CleanupDescription() + Documentation = new() { + Description = requestBodySchema.Description.CleanupDescription() + }, }); method.RequestBodyContentType = operation.RequestBody.Content.First(x => x.Value.Schema == requestBodySchema).Key; } else if (operation.RequestBody?.Content?.Any() ?? false) { @@ -951,7 +991,9 @@ private void AddRequestBuilderMethodParameters(OpenApiUrlTreeNode currentNode, O Name = "body", Optional = false, Kind = CodeParameterKind.RequestBody, - Description = "Binary request body", + Documentation = new() { + Description = "Binary request body", + }, Type = new CodeType { Name = "binary", IsExternal = true, @@ -965,7 +1007,9 @@ private void AddRequestBuilderMethodParameters(OpenApiUrlTreeNode currentNode, O Optional = true, Type = new CodeType { Name = requestConfigClass.Name, TypeDefinition = requestConfigClass, ActionOf = true }, Kind = CodeParameterKind.RequestConfiguration, - Description = "Configuration for the request such as headers, query parameters, and middleware options.", + Documentation = new() { + Description = "Configuration for the request such as headers, query parameters, and middleware options.", + }, }); } private string GetModelsNamespaceNameFromReferenceId(string referenceId) { @@ -1139,7 +1183,9 @@ private CodeElement AddModelDeclarationIfDoesntExist(OpenApiUrlTreeNode currentN if(schema.IsEnum()) { var newEnum = new CodeEnum { Name = declarationName,//TODO set the flag property - Description = currentNode.GetPathItemDescription(Constants.DefaultOpenApiLabel), + Documentation = new() { + Description = currentNode.GetPathItemDescription(Constants.DefaultOpenApiLabel), + }, }; SetEnumOptions(schema, newEnum); return currentNamespace.AddEnum(newEnum).First(); @@ -1160,7 +1206,9 @@ private static void SetEnumOptions(OpenApiSchema schema, CodeEnum target) { var newOption = new CodeEnumOption { Name = (optionDescription?.Name ?? enumValue).CleanupSymbolName(), SerializationName = !string.IsNullOrEmpty(optionDescription?.Name) ? enumValue : null, - Description = optionDescription?.Description, + Documentation = new() { + Description = optionDescription?.Description, + }, }; if(!string.IsNullOrEmpty(newOption.Name)) target.AddOption(newOption); @@ -1185,9 +1233,11 @@ private CodeClass AddModelClass(OpenApiUrlTreeNode currentNode, OpenApiSchema sc var newClass = currentNamespace.AddClass(new CodeClass { Name = declarationName, Kind = CodeClassKind.Model, - Description = schema.Description.CleanupDescription() ?? (string.IsNullOrEmpty(schema.Reference?.Id) ? - currentNode.GetPathItemDescription(Constants.DefaultOpenApiLabel) : - null),// if it's a referenced component, we shouldn't use the path item description as it makes it indeterministic + Documentation = new() { + Description = schema.Description.CleanupDescription() ?? (string.IsNullOrEmpty(schema.Reference?.Id) ? + currentNode.GetPathItemDescription(Constants.DefaultOpenApiLabel) : + null),// if it's a referenced component, we shouldn't use the path item description as it makes it indeterministic + }, }).First(); if(inheritsFrom != null) newClass.StartBlock.Inherits = new CodeType { TypeDefinition = inheritsFrom, Name = inheritsFrom.Name }; @@ -1214,7 +1264,9 @@ private void InitializeInheritanceIndex() { public static void AddDiscriminatorMethod(CodeClass newClass, string discriminatorPropertyName, IEnumerable> discriminatorMappings) { var factoryMethod = new CodeMethod { Name = "CreateFromDiscriminatorValue", - Description = "Creates a new instance of the appropriate class based on discriminator value", + Documentation = new() { + Description = "Creates a new instance of the appropriate class based on discriminator value", + }, ReturnType = new CodeType { TypeDefinition = newClass, Name = newClass.Name, IsNullable = false }, Kind = CodeMethodKind.Factory, IsStatic = true, @@ -1226,7 +1278,9 @@ public static void AddDiscriminatorMethod(CodeClass newClass, string discriminat factoryMethod.AddParameter(new CodeParameter { Name = "parseNode", Kind = CodeParameterKind.ParseNode, - Description = "The parse node to use to read the discriminator value and create the object", + Documentation = new() { + Description = "The parse node to use to read the discriminator value and create the object", + }, Optional = false, Type = new CodeType { Name = ParseNodeInterface, IsExternal = true }, }); @@ -1296,7 +1350,9 @@ internal static void AddSerializationMembers(CodeClass model, bool includeAdditi Name = FieldDeserializersMethodName, Kind = CodeMethodKind.Deserializer, Access = AccessModifier.Public, - Description = "The deserialization information for the current model", + Documentation = new() { + Description = "The deserialization information for the current model", + }, IsAsync = false, ReturnType = new CodeType { Name = serializationPropsType, @@ -1312,16 +1368,20 @@ internal static void AddSerializationMembers(CodeClass model, bool includeAdditi Name = SerializeMethodName, Kind = CodeMethodKind.Serializer, IsAsync = false, - Description = "Serializes information the current object", + Documentation = new() { + Description = "Serializes information the current object", + }, ReturnType = new CodeType { Name = voidType, IsNullable = false, IsExternal = true }, Parent = model, }; var parameter = new CodeParameter { Name = "writer", - Description = "Serialization writer to use to serialize this model", + Documentation = new() { + Description = "Serialization writer to use to serialize this model", + }, Kind = CodeParameterKind.Serializer, Type = new CodeType { Name = "ISerializationWriter", IsExternal = true, IsNullable = false }, - }; + }; serializeMethod.AddParameter(parameter); model.AddMethod(serializeMethod); @@ -1335,7 +1395,9 @@ internal static void AddSerializationMembers(CodeClass model, bool includeAdditi Access = AccessModifier.Public, DefaultValue = "new Dictionary()", Kind = CodePropertyKind.AdditionalData, - Description = "Stores additional data not described in the OpenAPI description found when deserializing. Can be used for serialization as well.", + Documentation = new() { + Description = "Stores additional data not described in the OpenAPI description found when deserializing. Can be used for serialization as well.", + }, Type = new CodeType { Name = "IDictionary", IsNullable = false, @@ -1356,7 +1418,9 @@ internal static void AddSerializationMembers(CodeClass model, bool includeAdditi Access = AccessModifier.Public, DefaultValue = "BackingStoreFactorySingleton.Instance.CreateBackingStore()", Kind = CodePropertyKind.BackingStore, - Description = "Stores model information.", + Documentation = new() { + Description = "Stores model information.", + }, ReadOnly = true, Type = new CodeType { Name = BackingStoreInterface, @@ -1379,7 +1443,9 @@ private CodeClass CreateOperationParameterClass(OpenApiUrlTreeNode node, Operati { Name = $"{parentClass.Name}{operationType}QueryParameters", Kind = CodeClassKind.QueryParameters, - Description = (operation.Description ?? operation.Summary).CleanupDescription(), + Documentation = new() { + Description = (operation.Description ?? operation.Summary).CleanupDescription(), + }, }).First(); foreach (var parameter in parameters) AddPropertyForParameter(parameter, parameterClass); @@ -1393,7 +1459,9 @@ private void AddPropertyForParameter(OpenApiParameter parameter, CodeClass param var prop = new CodeProperty { Name = parameter.Name.SanitizeParameterNameForCodeSymbols(), - Description = parameter.Description.CleanupDescription(), + Documentation = new() { + Description = parameter.Description.CleanupDescription(), + }, Kind = CodePropertyKind.QueryParameter, Type = GetPrimitiveType(parameter.Schema), }; diff --git a/src/Kiota.Builder/Refiners/CommonLanguageRefiner.cs b/src/Kiota.Builder/Refiners/CommonLanguageRefiner.cs index 1e8c60dbaf..18d9742017 100644 --- a/src/Kiota.Builder/Refiners/CommonLanguageRefiner.cs +++ b/src/Kiota.Builder/Refiners/CommonLanguageRefiner.cs @@ -117,7 +117,9 @@ current.Parent is CodeClass parentClass && IsAsync = false, Kind = CodeMethodKind.Getter, ReturnType = currentProperty.Type.Clone() as CodeTypeBase, - Description = $"Gets the {propertyOriginalName} property value. {currentProperty.Description}", + Documentation = new () { + Description = $"Gets the {propertyOriginalName} property value. {currentProperty.Documentation.Description}", + }, AccessedProperty = currentProperty, }).First(); currentProperty.Getter.Name = $"{getterPrefix}{accessorName}"; // so we don't get an exception for duplicate names when no prefix @@ -126,7 +128,9 @@ current.Parent is CodeClass parentClass && Access = AccessModifier.Public, IsAsync = false, Kind = CodeMethodKind.Setter, - Description = $"Sets the {propertyOriginalName} property value. {currentProperty.Description}", + Documentation = new () { + Description = $"Sets the {propertyOriginalName} property value. {currentProperty.Documentation.Description}", + }, AccessedProperty = currentProperty, ReturnType = new CodeType { Name = "void", @@ -140,7 +144,9 @@ current.Parent is CodeClass parentClass && setter.AddParameter(new CodeParameter { Name = "value", Kind = CodeParameterKind.SetterValue, - Description = $"Value to set for the {current.Name} property.", + Documentation = new () { + Description = $"Value to set for the {current.Name} property.", + }, Optional = parameterAsOptional, Type = currentProperty.Type.Clone() as CodeTypeBase, }); @@ -162,7 +168,9 @@ protected static void AddConstructorsForDefaultValues(CodeElement current, bool Name = "void" }, IsAsync = false, - Description = $"Instantiates a new {current.Name} and sets the default values." + Documentation = new () { + Description = $"Instantiates a new {current.Name} and sets the default values.", + }, }); CrawlTree(current, x => AddConstructorsForDefaultValues(x, addIfInherited, forceAdd, classKindsToExclude)); } @@ -385,12 +393,17 @@ private static CodeTypeBase ConvertComposedTypeToWrapper(CodeClass codeClass, Co newClass = @namespace.AddClass(new CodeClass { Name = codeComposedType.Name, - Description = description + Documentation = new() { + Description = description, + }, }).Last(); } else if (codeComposedType.TargetNamespace is CodeNamespace targetNamespace) { newClass = targetNamespace.AddClass(new CodeClass { Name = codeComposedType.Name, - Description = description}) + Documentation = new() { + Description = description + }, + }) .First(); newClass.AddUsing(codeClass.Usings .Where(static x => x.IsExternal) @@ -401,7 +414,10 @@ private static CodeTypeBase ConvertComposedTypeToWrapper(CodeClass codeClass, Co codeComposedType.Name = $"{codeComposedType.Name}Wrapper"; newClass = codeClass.AddInnerClass(new CodeClass { Name = codeComposedType.Name, - Description = description}) + Documentation = new() { + Description = description + }, + }) .First(); } newClass.AddProperty(codeComposedType @@ -409,7 +425,9 @@ private static CodeTypeBase ConvertComposedTypeToWrapper(CodeClass codeClass, Co .Select(x => new CodeProperty { Name = x.Name, Type = x, - Description = $"Composed type representation for type {x.Name}" + Documentation = new() { + Description = $"Composed type representation for type {x.Name}" + }, }).ToArray()); if(codeComposedType.Types.All(static x => x.TypeDefinition is CodeClass targetClass && targetClass.IsOfKind(CodeClassKind.Model) || x.TypeDefinition is CodeEnum || x.TypeDefinition is null)) @@ -418,7 +436,9 @@ private static CodeTypeBase ConvertComposedTypeToWrapper(CodeClass codeClass, Co newClass.AddProperty(new CodeProperty { Name = "serializationHint", Type = new CodeType { Name = "string" }, - Description = "Serialization hint for the current wrapper.", + Documentation = new() { + Description = "Serialization hint for the current wrapper.", + }, Access = AccessModifier.Public, Kind = CodePropertyKind.SerializationHint, }); @@ -624,7 +644,9 @@ currentElement.Parent is CodeClass parentClass && Name = "rawUrl", Type = new CodeType { Name = "string", IsExternal = true }, Optional = false, - Description = "The raw URL to use for the request builder.", + Documentation = new() { + Description = "The raw URL to use for the request builder.", + }, Kind = CodeParameterKind.RawUrl, }); parentClass.AddMethod(overloadCtor); @@ -969,7 +991,9 @@ public void AddQueryParameterMapperMethod(CodeElement currentElement, string met IsAsync = false, IsStatic = false, Kind = CodeMethodKind.QueryParametersMapper, - Description = "Maps the query parameters names to their encoded names for the URI template parsing.", + Documentation = new() { + Description = "Maps the query parameters names to their encoded names for the URI template parsing.", + }, }).First(); method.AddParameter(new CodeParameter { Name = parameterName, @@ -979,7 +1003,9 @@ public void AddQueryParameterMapperMethod(CodeElement currentElement, string met IsNullable = true, }, Optional = false, - Description = "The original query parameter name in the class.", + Documentation = new() { + Description = "The original query parameter name in the class.", + }, }); } CrawlTree(currentElement, x => AddQueryParameterMapperMethod(x, methodName, parameterName)); diff --git a/src/Kiota.Builder/Refiners/GoRefiner.cs b/src/Kiota.Builder/Refiners/GoRefiner.cs index 799fe1cebd..41a4dd4cbe 100644 --- a/src/Kiota.Builder/Refiners/GoRefiner.cs +++ b/src/Kiota.Builder/Refiners/GoRefiner.cs @@ -137,7 +137,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.Description = ContextVarDescription; + parameter.Documentation.Description = ContextVarDescription; parameter.Kind = CodeParameterKind.Cancellation; parameter.Optional = false; parameter.Type.Name = conventions.ContextVarTypeName; @@ -158,7 +158,9 @@ private static void AddContextParameterToGeneratorMethods(CodeElement currentEle }, Kind = CodeParameterKind.Cancellation, Optional = false, - Description = ContextVarDescription, + Documentation = { + Description = ContextVarDescription, + }, }); CrawlTree(currentElement, AddContextParameterToGeneratorMethods); } @@ -223,7 +225,7 @@ private static void ReplaceRequestBuilderPropertiesByMethods(CodeElement current Name = currentProperty.Name, ReturnType = currentProperty.Type, Access = AccessModifier.Public, - Description = currentProperty.Description, + Documentation = currentProperty.Documentation.Clone() as CodeDocumentation, IsAsync = false, Kind = CodeMethodKind.RequestBuilderBackwardCompatibility, }); diff --git a/src/Kiota.Builder/Refiners/JavaRefiner.cs b/src/Kiota.Builder/Refiners/JavaRefiner.cs index ce3e23f583..ab521e74e4 100644 --- a/src/Kiota.Builder/Refiners/JavaRefiner.cs +++ b/src/Kiota.Builder/Refiners/JavaRefiner.cs @@ -108,7 +108,9 @@ currentMethod.Parent is CodeClass parentClass && IsExternal = true }, Optional = false, - Description = "Discriminator value from the payload", + Documentation = new() { + Description = "Discriminator value from the payload", + }, Name = "discriminatorValue" }); parentClass.AddMethod(newMethod); diff --git a/src/Kiota.Builder/Refiners/PythonRefiner.cs b/src/Kiota.Builder/Refiners/PythonRefiner.cs index 312ba227cc..90caf6fd9d 100644 --- a/src/Kiota.Builder/Refiners/PythonRefiner.cs +++ b/src/Kiota.Builder/Refiners/PythonRefiner.cs @@ -157,7 +157,7 @@ private static void CorrectMethodType(CodeMethod currentMethod) { if(urlTplParams != null && urlTplParams.Type is CodeType originalType) { originalType.Name = "Dict[str, Any]"; - urlTplParams.Description = "The raw url or the Url template parameters for the request."; + urlTplParams.Documentation.Description = "The raw url or the Url template parameters for the request."; var unionType = new CodeUnionType { Name = "raw_url_or_template_parameters", IsNullable = true, diff --git a/src/Kiota.Builder/Refiners/ShellRefiner.cs b/src/Kiota.Builder/Refiners/ShellRefiner.cs index 761f7adffd..43f7c05949 100644 --- a/src/Kiota.Builder/Refiners/ShellRefiner.cs +++ b/src/Kiota.Builder/Refiners/ShellRefiner.cs @@ -90,7 +90,7 @@ private static void CreateCommandBuilders(CodeElement currentElement) var rootMethod = new CodeMethod { Name = "BuildRootCommand", - Description = clientConstructor.Description, + Documentation = clientConstructor.Documentation.Clone() as CodeDocumentation, IsAsync = false, Kind = CodeMethodKind.CommandBuilder, ReturnType = new CodeType { Name = "Command", IsExternal = true }, @@ -116,7 +116,7 @@ private static void CreateCommandBuildersFromRequestExecutors(CodeClass currentC clone.IsAsync = false; clone.Name = $"Build{cmdName}Command"; - clone.Description = requestMethod.Description; + clone.Documentation = requestMethod.Documentation.Clone() as CodeDocumentation; clone.ReturnType = CreateCommandType(); clone.Kind = CodeMethodKind.CommandBuilder; clone.OriginalMethod = requestMethod; @@ -137,11 +137,10 @@ private static void CreateCommandBuildersFromIndexers(CodeClass currentClass, IE IsAsync = false, Kind = CodeMethodKind.CommandBuilder, OriginalIndexer = indexer, - Description = indexer.Description, + Documentation = indexer.Documentation.Clone() as CodeDocumentation, + // ReturnType setter assigns the parent + ReturnType = CreateCommandType() }; - - // ReturnType setter assigns the parent - method.ReturnType = CreateCommandType(); currentClass.AddMethod(method); currentClass.RemoveChildElement(indexer); } @@ -163,12 +162,12 @@ private static CodeMethod CreateBuildCommandMethod(CodeProperty navProperty, Cod IsAsync = false, Name = $"Build{navProperty.Name.ToFirstCharacterUpperCase()}Command", Kind = CodeMethodKind.CommandBuilder, - Description = navProperty.Description + Documentation = navProperty.Documentation.Clone() as CodeDocumentation, + ReturnType = CreateCommandType(), + AccessedProperty = navProperty, + SimpleName = navProperty.Name, + Parent = parent }; - codeMethod.ReturnType = CreateCommandType(); - codeMethod.AccessedProperty = navProperty; - codeMethod.SimpleName = navProperty.Name; - codeMethod.Parent = parent; return codeMethod; } diff --git a/src/Kiota.Builder/Refiners/SwiftRefiner.cs b/src/Kiota.Builder/Refiners/SwiftRefiner.cs index a030bb9962..8c014253c1 100644 --- a/src/Kiota.Builder/Refiners/SwiftRefiner.cs +++ b/src/Kiota.Builder/Refiners/SwiftRefiner.cs @@ -175,7 +175,9 @@ private void AddRootClassForExtensions(CodeElement current) { clientNamespace.AddClass(new CodeClass { Name = clientNamespace.Name.Split('.', StringSplitOptions.RemoveEmptyEntries).Last().ToFirstCharacterUpperCase(), Kind = CodeClassKind.BarrelInitializer, - Description = "Root class for extensions", + Documentation = new() { + Description = "Root class for extensions", + }, }); } } diff --git a/src/Kiota.Builder/Refiners/TypeScriptRefiner.cs b/src/Kiota.Builder/Refiners/TypeScriptRefiner.cs index b1116f32eb..0522b8e184 100644 --- a/src/Kiota.Builder/Refiners/TypeScriptRefiner.cs +++ b/src/Kiota.Builder/Refiners/TypeScriptRefiner.cs @@ -233,7 +233,7 @@ private static void CorrectMethodType(CodeMethod currentMethod) { if(urlTplParams != null && urlTplParams.Type is CodeType originalType) { originalType.Name = "Record"; - urlTplParams.Description = "The raw url or the Url template parameters for the request."; + urlTplParams.Documentation.Description = "The raw url or the Url template parameters for the request."; var unionType = new CodeUnionType { Name = "rawUrlOrTemplateParameters", IsNullable = true, diff --git a/src/Kiota.Builder/Writers/CSharp/CodeClassDeclarationWriter.cs b/src/Kiota.Builder/Writers/CSharp/CodeClassDeclarationWriter.cs index 641cebd85c..4c49891909 100644 --- a/src/Kiota.Builder/Writers/CSharp/CodeClassDeclarationWriter.cs +++ b/src/Kiota.Builder/Writers/CSharp/CodeClassDeclarationWriter.cs @@ -31,7 +31,7 @@ public override void WriteCodeElement(ClassDeclaration codeElement, LanguageWrit .Where(x => x != null); var derivation = derivedTypes.Any() ? ": " + derivedTypes.Select(x => x.ToFirstCharacterUpperCase()).Aggregate((x, y) => $"{x}, {y}") + " " : string.Empty; if(codeElement.Parent is CodeClass parentClass) - conventions.WriteShortDescription(parentClass.Description, writer); + conventions.WriteShortDescription(parentClass.Documentation.Description, writer); writer.WriteLine($"public class {codeElement.Name.ToFirstCharacterUpperCase()} {derivation}{{"); writer.IncreaseIndent(); } diff --git a/src/Kiota.Builder/Writers/CSharp/CodeEnumWriter.cs b/src/Kiota.Builder/Writers/CSharp/CodeEnumWriter.cs index 8e7e0fe8eb..47c11fe9de 100644 --- a/src/Kiota.Builder/Writers/CSharp/CodeEnumWriter.cs +++ b/src/Kiota.Builder/Writers/CSharp/CodeEnumWriter.cs @@ -20,12 +20,12 @@ public override void WriteCodeElement(CodeEnum codeElement, LanguageWriter write writer.StartBlock($"namespace {codeNamespace.Name} {{"); if (codeElement.Flags) writer.WriteLine("[Flags]"); - conventions.WriteShortDescription(codeElement.Description, writer); + conventions.WriteShortDescription(codeElement.Documentation.Description, writer); writer.WriteLine($"public enum {codeElement.Name.ToFirstCharacterUpperCase()} {{"); writer.IncreaseIndent(); var idx = 0; foreach(var option in codeElement.Options) { - conventions.WriteShortDescription(option.Description, writer); + conventions.WriteShortDescription(option.Documentation.Description, writer); writer.WriteLine($"{option.Name.ToFirstCharacterUpperCase()}{(codeElement.Flags ? " = " + GetEnumFlag(idx) : string.Empty)},"); idx++; } diff --git a/src/Kiota.Builder/Writers/CSharp/CodeIndexerWriter.cs b/src/Kiota.Builder/Writers/CSharp/CodeIndexerWriter.cs index b1bd60f247..1788102826 100644 --- a/src/Kiota.Builder/Writers/CSharp/CodeIndexerWriter.cs +++ b/src/Kiota.Builder/Writers/CSharp/CodeIndexerWriter.cs @@ -10,7 +10,7 @@ public override void WriteCodeElement(CodeIndexer codeElement, LanguageWriter wr var parentClass = codeElement.Parent as CodeClass; var pathParametersProp = parentClass.GetPropertyOfKind(CodePropertyKind.PathParameters); var returnType = conventions.GetTypeString(codeElement.ReturnType, codeElement); - conventions.WriteShortDescription(codeElement.Description, writer); + conventions.WriteShortDescription(codeElement.Documentation.Description, writer); writer.WriteLine($"public {returnType} this[{conventions.GetTypeString(codeElement.IndexType, codeElement)} position] {{ get {{"); writer.IncreaseIndent(); conventions.AddParametersAssignment(writer, pathParametersProp.Type, pathParametersProp.Name.ToFirstCharacterUpperCase(), (codeElement.IndexType, codeElement.SerializationName, "position")); diff --git a/src/Kiota.Builder/Writers/CSharp/CodeMethodWriter.cs b/src/Kiota.Builder/Writers/CSharp/CodeMethodWriter.cs index e59903eadb..4330bbcdc4 100644 --- a/src/Kiota.Builder/Writers/CSharp/CodeMethodWriter.cs +++ b/src/Kiota.Builder/Writers/CSharp/CodeMethodWriter.cs @@ -525,16 +525,16 @@ protected string GetSendRequestMethodName(bool isVoid, CodeElement currentElemen } private void WriteMethodDocumentation(CodeMethod code, LanguageWriter writer) { - var isDescriptionPresent = !string.IsNullOrEmpty(code.Description); - var parametersWithDescription = code.Parameters.Where(x => !string.IsNullOrEmpty(code.Description)); + var isDescriptionPresent = !string.IsNullOrEmpty(code.Documentation.Description); + var parametersWithDescription = code.Parameters.Where(x => !string.IsNullOrEmpty(code.Documentation.Description)); if (isDescriptionPresent || parametersWithDescription.Any()) { writer.WriteLine($"{conventions.DocCommentPrefix}"); if (isDescriptionPresent) - writer.WriteLine($"{conventions.DocCommentPrefix}{code.Description.CleanupXMLString()}"); + writer.WriteLine($"{conventions.DocCommentPrefix}{code.Documentation.Description.CleanupXMLString()}"); writer.WriteLine($"{conventions.DocCommentPrefix}"); foreach (var paramWithDescription in parametersWithDescription.OrderBy(x => x.Name)) - writer.WriteLine($"{conventions.DocCommentPrefix}{paramWithDescription.Description.CleanupXMLString()}"); + writer.WriteLine($"{conventions.DocCommentPrefix}{paramWithDescription.Documentation.Description.CleanupXMLString()}"); } } private static readonly BaseCodeParameterOrderComparer parameterOrderComparer = new(); diff --git a/src/Kiota.Builder/Writers/CSharp/CodePropertyWriter.cs b/src/Kiota.Builder/Writers/CSharp/CodePropertyWriter.cs index 399f4f17e5..3666efa1f4 100644 --- a/src/Kiota.Builder/Writers/CSharp/CodePropertyWriter.cs +++ b/src/Kiota.Builder/Writers/CSharp/CodePropertyWriter.cs @@ -13,7 +13,7 @@ public override void WriteCodeElement(CodeProperty codeElement, LanguageWriter w var simpleBody = $"get; {setterAccessModifier}set;"; var propertyType = conventions.GetTypeString(codeElement.Type, codeElement); var defaultValue = string.Empty; - conventions.WriteShortDescription(codeElement.Description, writer); + conventions.WriteShortDescription(codeElement.Documentation.Description, writer); switch(codeElement.Kind) { case CodePropertyKind.RequestBuilder: writer.WriteLine($"{conventions.GetAccessModifier(codeElement.Access)} {propertyType} {codeElement.Name.ToFirstCharacterUpperCase()} {{ get =>"); diff --git a/src/Kiota.Builder/Writers/Go/CodeClassDeclarationWriter.cs b/src/Kiota.Builder/Writers/Go/CodeClassDeclarationWriter.cs index c9436354d1..9eb5b5476a 100644 --- a/src/Kiota.Builder/Writers/Go/CodeClassDeclarationWriter.cs +++ b/src/Kiota.Builder/Writers/Go/CodeClassDeclarationWriter.cs @@ -10,7 +10,7 @@ public CodeClassDeclarationWriter(GoConventionService conventionService) : base( protected override void WriteTypeDeclaration(ClassDeclaration codeElement, LanguageWriter writer) { var className = codeElement.Name.ToFirstCharacterUpperCase(); var currentClass = codeElement.Parent as CodeClass; - conventions.WriteShortDescription($"{className} {currentClass.Description.ToFirstCharacterLowerCase()}", writer); + conventions.WriteShortDescription($"{className} {currentClass.Documentation.Description.ToFirstCharacterLowerCase()}", writer); writer.StartBlock($"type {className} struct {{"); if(codeElement.Inherits?.AllTypes?.Any() ?? false) { var parentTypeName = conventions.GetTypeString(codeElement.Inherits.AllTypes.First(), currentClass, true, false); diff --git a/src/Kiota.Builder/Writers/Go/CodeEnumWriter.cs b/src/Kiota.Builder/Writers/Go/CodeEnumWriter.cs index e7c9aed9f1..78783ed52b 100644 --- a/src/Kiota.Builder/Writers/Go/CodeEnumWriter.cs +++ b/src/Kiota.Builder/Writers/Go/CodeEnumWriter.cs @@ -19,7 +19,7 @@ public override void WriteCodeElement(CodeEnum codeElement, LanguageWriter write writer.DecreaseIndent(); writer.WriteLine(")"); var typeName = codeElement.Name.ToFirstCharacterUpperCase(); - conventions.WriteShortDescription(codeElement.Description, writer); + conventions.WriteShortDescription(codeElement.Documentation.Description, writer); writer.WriteLines($"type {typeName} int", string.Empty, "const ("); @@ -27,8 +27,8 @@ public override void WriteCodeElement(CodeEnum codeElement, LanguageWriter write var iotaSuffix = $" {typeName} = iota"; var enumOptions = codeElement.Options; foreach (var item in enumOptions) { - if(!string.IsNullOrEmpty(item.Description)) - writer.WriteLine($"// {item.Description}"); + if(!string.IsNullOrEmpty(item.Documentation.Description)) + writer.WriteLine($"// {item.Documentation.Description}"); writer.WriteLine($"{item.Name.ToUpperInvariant()}_{typeName.ToUpperInvariant()}{iotaSuffix}"); if (!string.IsNullOrEmpty(iotaSuffix)) iotaSuffix = string.Empty; diff --git a/src/Kiota.Builder/Writers/Go/CodeInterfaceDeclarationWriter.cs b/src/Kiota.Builder/Writers/Go/CodeInterfaceDeclarationWriter.cs index 1af51c11b3..bcd07f8028 100644 --- a/src/Kiota.Builder/Writers/Go/CodeInterfaceDeclarationWriter.cs +++ b/src/Kiota.Builder/Writers/Go/CodeInterfaceDeclarationWriter.cs @@ -10,7 +10,7 @@ protected override void WriteTypeDeclaration(InterfaceDeclaration codeElement, L { var inter = codeElement.Parent as CodeInterface; var interName = codeElement.Name.ToFirstCharacterUpperCase(); - conventions.WriteShortDescription($"{interName} {inter.Description.ToFirstCharacterLowerCase()}", writer); + conventions.WriteShortDescription($"{interName} {inter.Documentation.Description.ToFirstCharacterLowerCase()}", writer); writer.WriteLine($"type {interName} interface {{"); writer.IncreaseIndent(); foreach (var implement in codeElement.Implements) { diff --git a/src/Kiota.Builder/Writers/Go/CodeMethodWriter.cs b/src/Kiota.Builder/Writers/Go/CodeMethodWriter.cs index d09019aef8..00f6fbe4de 100644 --- a/src/Kiota.Builder/Writers/Go/CodeMethodWriter.cs +++ b/src/Kiota.Builder/Writers/Go/CodeMethodWriter.cs @@ -230,8 +230,8 @@ private void WriteFactoryMethodBodyForUnionModelForUnDiscriminatedTypes(CodeClas } private void WriteMethodDocumentation(CodeMethod code, string methodName, LanguageWriter writer) { - if(!string.IsNullOrEmpty(code.Description)) - conventions.WriteShortDescription($"{methodName.ToFirstCharacterUpperCase()} {code.Description.ToFirstCharacterLowerCase()}", writer); + if(!string.IsNullOrEmpty(code.Documentation.Description)) + conventions.WriteShortDescription($"{methodName.ToFirstCharacterUpperCase()} {code.Documentation.Description.ToFirstCharacterLowerCase()}", 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 32dc062e2f..32e3b27553 100644 --- a/src/Kiota.Builder/Writers/Go/CodePropertyWriter.cs +++ b/src/Kiota.Builder/Writers/Go/CodePropertyWriter.cs @@ -19,7 +19,7 @@ public override void WriteCodeElement(CodeProperty codeElement, LanguageWriter w suffix = $" `uriparametername:\"{codeElement.SerializationName}\"`"; goto default; default: - conventions.WriteShortDescription(codeElement.Description, writer); + conventions.WriteShortDescription(codeElement.Documentation.Description, writer); writer.WriteLine($"{propertyName} {returnType}{suffix}"); break; } diff --git a/src/Kiota.Builder/Writers/Java/CodeClassDeclarationWriter.cs b/src/Kiota.Builder/Writers/Java/CodeClassDeclarationWriter.cs index 6ad9267628..5d4e2c4a1f 100644 --- a/src/Kiota.Builder/Writers/Java/CodeClassDeclarationWriter.cs +++ b/src/Kiota.Builder/Writers/Java/CodeClassDeclarationWriter.cs @@ -29,7 +29,7 @@ public override void WriteCodeElement(ClassDeclaration codeElement, LanguageWrit } 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)}"); - conventions.WriteShortDescription((codeElement.Parent as CodeClass)?.Description, writer); + conventions.WriteShortDescription((codeElement.Parent as CodeClass)?.Documentation.Description, writer); var innerClassStatic = codeElement.Parent is CodeClass currentClass && currentClass.IsOfKind(CodeClassKind.Model) && currentClass.Parent is CodeClass ? "static " : string.Empty; //https://stackoverflow.com/questions/47541459/no-enclosing-instance-is-accessible-must-qualify-the-allocation-with-an-enclosi writer.WriteLine($"public {innerClassStatic}class {codeElement.Name.ToFirstCharacterUpperCase()}{derivation} {{"); writer.IncreaseIndent(); diff --git a/src/Kiota.Builder/Writers/Java/CodeEnumWriter.cs b/src/Kiota.Builder/Writers/Java/CodeEnumWriter.cs index c24dbecdfd..d4e0c67f3c 100644 --- a/src/Kiota.Builder/Writers/Java/CodeEnumWriter.cs +++ b/src/Kiota.Builder/Writers/Java/CodeEnumWriter.cs @@ -18,12 +18,12 @@ public override void WriteCodeElement(CodeEnum codeElement, LanguageWriter write "import com.microsoft.kiota.serialization.ValuedEnum;", "import java.util.Objects;", string.Empty); - conventions.WriteShortDescription(codeElement.Description, writer); + conventions.WriteShortDescription(codeElement.Documentation.Description, writer); writer.WriteLine($"public enum {enumName} implements ValuedEnum {{"); writer.IncreaseIndent(); var lastEnumOption = enumOptions.Last(); foreach(var enumOption in enumOptions) { - conventions.WriteShortDescription(enumOption.Description, writer); + conventions.WriteShortDescription(enumOption.Documentation.Description, writer); writer.WriteLine($"{enumOption.Name.ToFirstCharacterUpperCase()}(\"{enumOption.Name}\"){(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 895d391a3f..5246d93efa 100644 --- a/src/Kiota.Builder/Writers/Java/CodeMethodWriter.cs +++ b/src/Kiota.Builder/Writers/Java/CodeMethodWriter.cs @@ -633,14 +633,14 @@ private string WriteMethodPrototype(CodeMethod code, LanguageWriter writer, stri return collectionCorrectedReturnType; } private void WriteMethodDocumentation(CodeMethod code, LanguageWriter writer) { - var isDescriptionPresent = !string.IsNullOrEmpty(code.Description); - var parametersWithDescription = code.Parameters.Where(x => !string.IsNullOrEmpty(code.Description)); + var isDescriptionPresent = !string.IsNullOrEmpty(code.Documentation.Description); + var parametersWithDescription = code.Parameters.Where(x => !string.IsNullOrEmpty(code.Documentation.Description)); if (isDescriptionPresent || parametersWithDescription.Any()) { writer.WriteLine(conventions.DocCommentStart); if(isDescriptionPresent) - writer.WriteLine($"{conventions.DocCommentPrefix}{JavaConventionService.RemoveInvalidDescriptionCharacters(code.Description)}"); + writer.WriteLine($"{conventions.DocCommentPrefix}{JavaConventionService.RemoveInvalidDescriptionCharacters(code.Documentation.Description)}"); foreach(var paramWithDescription in parametersWithDescription.OrderBy(x => x.Name)) - writer.WriteLine($"{conventions.DocCommentPrefix}@param {paramWithDescription.Name} {JavaConventionService.RemoveInvalidDescriptionCharacters(paramWithDescription.Description)}"); + writer.WriteLine($"{conventions.DocCommentPrefix}@param {paramWithDescription.Name} {JavaConventionService.RemoveInvalidDescriptionCharacters(paramWithDescription.Documentation.Description)}"); if(code.IsAsync) writer.WriteLine($"{conventions.DocCommentPrefix}@return a CompletableFuture of {code.ReturnType.Name}"); diff --git a/src/Kiota.Builder/Writers/Java/CodePropertyWriter.cs b/src/Kiota.Builder/Writers/Java/CodePropertyWriter.cs index 5516586b8f..920b8d55d6 100644 --- a/src/Kiota.Builder/Writers/Java/CodePropertyWriter.cs +++ b/src/Kiota.Builder/Writers/Java/CodePropertyWriter.cs @@ -7,7 +7,7 @@ public class CodePropertyWriter : BaseElementWriter orNullReturn) { - var methodDescription = codeMethod.Description ?? string.Empty; + var methodDescription = codeMethod.Documentation.Description ?? string.Empty; var hasMethodDescription = !string.IsNullOrEmpty(methodDescription.Trim(' ')); var parametersWithDescription = codeMethod.Parameters; @@ -175,8 +175,8 @@ private string GetParameterDocString(CodeMethod codeMethod, CodeParameter x, boo { return codeMethod.Kind switch { - CodeMethodKind.Setter => $"{conventions.DocCommentPrefix} @param {(isSetterForAdditionalData ? "array $value": conventions.GetParameterDocNullable(x, x))} {x?.Description}", - _ => $"{conventions.DocCommentPrefix}@param {conventions.GetParameterDocNullable(x, x)} {x.Description}" + CodeMethodKind.Setter => $"{conventions.DocCommentPrefix} @param {(isSetterForAdditionalData ? "array $value": conventions.GetParameterDocNullable(x, x))} {x?.Documentation.Description}", + _ => $"{conventions.DocCommentPrefix}@param {conventions.GetParameterDocNullable(x, x)} {x.Documentation.Description}" }; } diff --git a/src/Kiota.Builder/Writers/Php/CodePropertyWriter.cs b/src/Kiota.Builder/Writers/Php/CodePropertyWriter.cs index bfc756a5a0..1cedcc57a3 100644 --- a/src/Kiota.Builder/Writers/Php/CodePropertyWriter.cs +++ b/src/Kiota.Builder/Writers/Php/CodePropertyWriter.cs @@ -28,7 +28,7 @@ public override void WriteCodeElement(CodeProperty codeElement, LanguageWriter w private void WritePropertyDocComment(CodeProperty codeProperty, LanguageWriter writer) { - var propertyDescription = codeProperty.Description; + var propertyDescription = codeProperty.Documentation.Description; var hasDescription = !string.IsNullOrEmpty(propertyDescription); var collectionKind = codeProperty.Type.IsArray || codeProperty.Type.IsCollection; @@ -59,7 +59,7 @@ private string GetCollectionDocString(CodeProperty codeProperty) private void WriteRequestBuilderBody(CodeProperty codeElement, LanguageWriter writer, string returnType, string propertyAccess, string propertyName) { - conventions.WriteShortDescription(codeElement.Description, writer); + conventions.WriteShortDescription(codeElement.Documentation.Description, writer); writer.WriteLine($"{propertyAccess} function {propertyName}(): {returnType} {{"); writer.IncreaseIndent(); conventions.AddRequestBuilderBody(returnType, writer); diff --git a/src/Kiota.Builder/Writers/Python/CodeClassDeclarationWriter.cs b/src/Kiota.Builder/Writers/Python/CodeClassDeclarationWriter.cs index ebfaecabab..4cc331ad30 100644 --- a/src/Kiota.Builder/Writers/Python/CodeClassDeclarationWriter.cs +++ b/src/Kiota.Builder/Writers/Python/CodeClassDeclarationWriter.cs @@ -25,7 +25,7 @@ public override void WriteCodeElement(ClassDeclaration codeElement, LanguageWrit } writer.WriteLine($"class {codeElement.Name.ToFirstCharacterUpperCase()}({derivation}):"); writer.IncreaseIndent(); - conventions.WriteShortDescription((codeElement.Parent as CodeClass)?.Description, writer); + conventions.WriteShortDescription((codeElement.Parent as CodeClass)?.Documentation.Description, writer); } private static void WriteExternalImports(ClassDeclaration codeElement, LanguageWriter writer) { diff --git a/src/Kiota.Builder/Writers/Python/CodeEnumWriter.cs b/src/Kiota.Builder/Writers/Python/CodeEnumWriter.cs index e5ec8bf6c0..106879529c 100644 --- a/src/Kiota.Builder/Writers/Python/CodeEnumWriter.cs +++ b/src/Kiota.Builder/Writers/Python/CodeEnumWriter.cs @@ -18,7 +18,7 @@ public override void WriteCodeElement(CodeEnum codeElement, LanguageWriter write } else { codeElement.Options.ToList().ForEach(x => { - conventions.WriteInLineDescription(x.Description, writer); + conventions.WriteInLineDescription(x.Documentation.Description, writer); writer.WriteLine($"{x.Name.ToFirstCharacterUpperCase()} = \"{x.SerializationName ?? x.Name}\","); }); } diff --git a/src/Kiota.Builder/Writers/Python/CodeMethodWriter.cs b/src/Kiota.Builder/Writers/Python/CodeMethodWriter.cs index 61d1255175..70db9ed38f 100644 --- a/src/Kiota.Builder/Writers/Python/CodeMethodWriter.cs +++ b/src/Kiota.Builder/Writers/Python/CodeMethodWriter.cs @@ -184,7 +184,7 @@ private void WriteDirectAccessProperties(CodeClass parentClass, LanguageWriter w .OrderByDescending(static x => x.Kind) .ThenBy(static x => x.Name)) { var returnType = conventions.GetTypeString(propWithDefault.Type, propWithDefault, true, writer); - conventions.WriteInLineDescription(propWithDefault.Description, writer); + conventions.WriteInLineDescription(propWithDefault.Documentation.Description, writer); writer.WriteLine($"self.{conventions.GetAccessModifier(propWithDefault.Access)}{propWithDefault.NamePrefix}{propWithDefault.Name.ToSnakeCase()}: {(propWithDefault.Type.IsNullable ? "Optional[" : string.Empty)}{returnType}{(propWithDefault.Type.IsNullable ? "]" : string.Empty)} = {propWithDefault.DefaultValue}"); writer.WriteLine(); } @@ -203,7 +203,7 @@ private void WriteSetterAccessPropertiesWithoutDefaults(CodeClass parentClass, L .OrderByDescending(static x => x.Kind) .ThenBy(static x => x.Name)) { var returnType = conventions.GetTypeString(propWithoutDefault.Type, propWithoutDefault, true, writer); - conventions.WriteInLineDescription(propWithoutDefault.Description, writer); + conventions.WriteInLineDescription(propWithoutDefault.Documentation.Description, writer); writer.WriteLine($"self.{conventions.GetAccessModifier(propWithoutDefault.Access)}{propWithoutDefault.NamePrefix}{propWithoutDefault.Name.ToSnakeCase()}: {(propWithoutDefault.Type.IsNullable ? "Optional[" : string.Empty)}{returnType}{(propWithoutDefault.Type.IsNullable ? "]" : string.Empty)} = None"); } } @@ -333,20 +333,20 @@ private void WriteSerializerBody(bool inherits, CodeClass parentClass, LanguageW writer.WriteLine($"writer.write_additional_data_value(self.{additionalDataProperty.Name.ToSnakeCase()})"); } private void WriteMethodDocumentation(CodeMethod code, LanguageWriter writer, string returnType, bool isVoid) { - var isDescriptionPresent = !string.IsNullOrEmpty(code.Description); - var parametersWithDescription = code.Parameters.Where(_ => !string.IsNullOrEmpty(code.Description)); + var isDescriptionPresent = !string.IsNullOrEmpty(code.Documentation.Description); + var parametersWithDescription = code.Parameters.Where(_ => !string.IsNullOrEmpty(code.Documentation.Description)); var nullablePrefix = code.ReturnType.IsNullable && !isVoid ? "Optional[" : string.Empty; var nullableSuffix = code.ReturnType.IsNullable && !isVoid ? "]" : string.Empty; if (isDescriptionPresent || parametersWithDescription.Any()) { writer.WriteLine(conventions.DocCommentStart); if(isDescriptionPresent) - writer.WriteLine($"{conventions.DocCommentPrefix}{PythonConventionService.RemoveInvalidDescriptionCharacters(code.Description)}"); + writer.WriteLine($"{conventions.DocCommentPrefix}{PythonConventionService.RemoveInvalidDescriptionCharacters(code.Documentation.Description)}"); if(parametersWithDescription.Any()) { writer.WriteLine("Args:"); writer.IncreaseIndent(); foreach(var paramWithDescription in parametersWithDescription.OrderBy(x => x.Name)) - writer.WriteLine($"{conventions.DocCommentPrefix}{paramWithDescription.Name}: {PythonConventionService.RemoveInvalidDescriptionCharacters(paramWithDescription.Description)}"); + writer.WriteLine($"{conventions.DocCommentPrefix}{paramWithDescription.Name}: {PythonConventionService.RemoveInvalidDescriptionCharacters(paramWithDescription.Documentation.Description)}"); writer.DecreaseIndent(); } if(!isVoid) diff --git a/src/Kiota.Builder/Writers/Python/CodePropertyWriter.cs b/src/Kiota.Builder/Writers/Python/CodePropertyWriter.cs index 49be5d7880..661546136a 100644 --- a/src/Kiota.Builder/Writers/Python/CodePropertyWriter.cs +++ b/src/Kiota.Builder/Writers/Python/CodePropertyWriter.cs @@ -17,7 +17,7 @@ public override void WriteCodeElement(CodeProperty codeElement, LanguageWriter w case CodePropertyKind.RequestBuilder: writer.WriteLine($"def {codeElement.Name.ToSnakeCase()}(self) -> {returnType}:"); writer.IncreaseIndent(); - conventions.WriteShortDescription(codeElement.Description, writer); + conventions.WriteShortDescription(codeElement.Documentation.Description, writer); conventions.AddRequestBuilderBody(parentClass, returnType, writer); writer.CloseBlock(string.Empty); break; @@ -25,7 +25,7 @@ public override void WriteCodeElement(CodeProperty codeElement, LanguageWriter w case CodePropertyKind.Headers: case CodePropertyKind.Options: case CodePropertyKind.QueryParameter: - conventions.WriteInLineDescription(codeElement.Description, writer); + conventions.WriteInLineDescription(codeElement.Documentation.Description, writer); writer.WriteLine($"{conventions.GetAccessModifier(codeElement.Access)}{codeElement.NamePrefix}{codeElement.Name.ToSnakeCase()}: {(codeElement.Type.IsNullable ? "Optional[" : string.Empty)}{returnType}{(codeElement.Type.IsNullable ? "]" : string.Empty)} = None"); writer.WriteLine(); break; diff --git a/src/Kiota.Builder/Writers/Ruby/CodeClassDeclarationWriter.cs b/src/Kiota.Builder/Writers/Ruby/CodeClassDeclarationWriter.cs index 564a7fd956..d4df05c61d 100644 --- a/src/Kiota.Builder/Writers/Ruby/CodeClassDeclarationWriter.cs +++ b/src/Kiota.Builder/Writers/Ruby/CodeClassDeclarationWriter.cs @@ -43,7 +43,7 @@ public override void WriteCodeElement(ClassDeclaration codeElement, LanguageWrit } var derivation = codeElement.Inherits == null ? string.Empty : $" < {codeElement.Inherits.Name.ToFirstCharacterUpperCase()}"; - conventions.WriteShortDescription((codeElement.Parent as CodeClass).Description, writer); + conventions.WriteShortDescription((codeElement.Parent as CodeClass).Documentation.Description, writer); writer.WriteLine($"class {codeElement.Name.ToFirstCharacterUpperCase()}{derivation}"); writer.IncreaseIndent(); var mixins = !codeElement.Implements.Any() ? string.Empty : $"include {codeElement.Implements.Select(x => x.Name).Aggregate((x,y) => x + ", " + y)}"; diff --git a/src/Kiota.Builder/Writers/Ruby/CodeEnumWriter.cs b/src/Kiota.Builder/Writers/Ruby/CodeEnumWriter.cs index 17b8c72c72..dc347f858e 100644 --- a/src/Kiota.Builder/Writers/Ruby/CodeEnumWriter.cs +++ b/src/Kiota.Builder/Writers/Ruby/CodeEnumWriter.cs @@ -15,7 +15,7 @@ public override void WriteCodeElement(CodeEnum codeElement, LanguageWriter write writer.WriteLine($"module {ns.Name.NormalizeNameSpaceName("::")}"); writer.IncreaseIndent(); } - conventions.WriteShortDescription(codeElement.Description, writer); + conventions.WriteShortDescription(codeElement.Documentation.Description, writer); writer.WriteLine($"{codeElement.Name.ToFirstCharacterUpperCase()} = {{"); writer.IncreaseIndent(); codeElement.Options.ToList().ForEach(x => writer.WriteLine($"{x.Name.ToFirstCharacterUpperCase()}: :{x.Name.ToFirstCharacterUpperCase()},")); diff --git a/src/Kiota.Builder/Writers/Ruby/CodeMethodWriter.cs b/src/Kiota.Builder/Writers/Ruby/CodeMethodWriter.cs index 062a67db8a..b25b4c7128 100644 --- a/src/Kiota.Builder/Writers/Ruby/CodeMethodWriter.cs +++ b/src/Kiota.Builder/Writers/Ruby/CodeMethodWriter.cs @@ -224,25 +224,25 @@ private void WriteSerializerBody(CodeClass parentClass, LanguageWriter writer) { } private static readonly BaseCodeParameterOrderComparer parameterOrderComparer = new(); private void WriteMethodPrototype(CodeMethod code, LanguageWriter writer) { - var methodName = (code.Kind switch { + var methodName = code.Kind switch { CodeMethodKind.Constructor or CodeMethodKind.ClientConstructor => "initialize", CodeMethodKind.Getter => $"{code.AccessedProperty?.Name?.ToSnakeCase()}", CodeMethodKind.Setter => $"{code.AccessedProperty?.Name?.ToSnakeCase()}", _ => code.Name.ToSnakeCase() - }); + }; var parameters = string.Join(", ", code.Parameters.OrderBy(x => x, parameterOrderComparer).Select(p=> conventions.GetParameterSignature(p, code).ToSnakeCase()).ToList()); writer.WriteLine($"def {methodName.ToSnakeCase()}({parameters}) "); writer.IncreaseIndent(); } private void WriteMethodDocumentation(CodeMethod code, LanguageWriter writer) { - var isDescriptionPresent = !string.IsNullOrEmpty(code.Description); - var parametersWithDescription = code.Parameters.Where(x => !string.IsNullOrEmpty(code.Description)); + var isDescriptionPresent = !string.IsNullOrEmpty(code.Documentation.Description); + var parametersWithDescription = code.Parameters.Where(x => !string.IsNullOrEmpty(code.Documentation.Description)); if (isDescriptionPresent || parametersWithDescription.Any()) { writer.WriteLine(conventions.DocCommentStart); if(isDescriptionPresent) - writer.WriteLine($"{conventions.DocCommentPrefix}{RubyConventionService.RemoveInvalidDescriptionCharacters(code.Description)}"); + writer.WriteLine($"{conventions.DocCommentPrefix}{RubyConventionService.RemoveInvalidDescriptionCharacters(code.Documentation.Description)}"); foreach(var paramWithDescription in parametersWithDescription.OrderBy(x => x.Name)) - writer.WriteLine($"{conventions.DocCommentPrefix}@param {paramWithDescription.Name} {RubyConventionService.RemoveInvalidDescriptionCharacters(paramWithDescription.Description)}"); + writer.WriteLine($"{conventions.DocCommentPrefix}@param {paramWithDescription.Name} {RubyConventionService.RemoveInvalidDescriptionCharacters(paramWithDescription.Documentation.Description)}"); if(code.IsAsync) writer.WriteLine($"{conventions.DocCommentPrefix}@return a CompletableFuture of {code.ReturnType.Name.ToSnakeCase()}"); diff --git a/src/Kiota.Builder/Writers/Ruby/CodePropertyWriter.cs b/src/Kiota.Builder/Writers/Ruby/CodePropertyWriter.cs index caf2e496f9..9ad652d8c8 100644 --- a/src/Kiota.Builder/Writers/Ruby/CodePropertyWriter.cs +++ b/src/Kiota.Builder/Writers/Ruby/CodePropertyWriter.cs @@ -7,7 +7,7 @@ public class CodePropertyWriter : BaseElementWriter WriteExecutableCommandOptions(LanguageWriter writer, List<( optionBuilder.Append($", getDefaultValue: ()=> {defaultValue}"); } - if (!string.IsNullOrEmpty(option.Description)) + if (!string.IsNullOrEmpty(option.Documentation.Description)) { - optionBuilder.Append($", description: \"{option.Description}\""); + optionBuilder.Append($", description: \"{option.Documentation.Description}\""); } optionBuilder.Append(") {"); @@ -338,8 +338,8 @@ private List WriteExecutableCommandOptions(LanguageWriter writer, List<( private static void WriteCommandDescription(CodeMethod codeElement, LanguageWriter writer) { - if (!string.IsNullOrWhiteSpace(codeElement.Description)) - writer.WriteLine($"command.Description = \"{codeElement.Description}\";"); + if (!string.IsNullOrWhiteSpace(codeElement.Documentation.Description)) + writer.WriteLine($"command.Description = \"{codeElement.Documentation.Description}\";"); } private void WriteContainerCommand(CodeMethod codeElement, LanguageWriter writer, CodeClass parent, string name) diff --git a/src/Kiota.Builder/Writers/Swift/CodeClassDeclarationWriter.cs b/src/Kiota.Builder/Writers/Swift/CodeClassDeclarationWriter.cs index 9df611b523..334b7246b8 100644 --- a/src/Kiota.Builder/Writers/Swift/CodeClassDeclarationWriter.cs +++ b/src/Kiota.Builder/Writers/Swift/CodeClassDeclarationWriter.cs @@ -15,7 +15,7 @@ protected override void WriteTypeDeclaration(ClassDeclaration codeElement, Langu .Where(x => x != null); var derivation = derivedTypes.Any() ? ": " + derivedTypes.Select(x => x.ToFirstCharacterUpperCase()).Aggregate((x, y) => $"{x}, {y}") + " " : string.Empty; if(codeElement.Parent is CodeClass parentClass) - conventions.WriteShortDescription(parentClass.Description, writer); + conventions.WriteShortDescription(parentClass.Documentation.Description, writer); writer.WriteLine($"public class {codeElement.Name.ToFirstCharacterUpperCase()} {derivation}{{"); writer.IncreaseIndent(); } diff --git a/src/Kiota.Builder/Writers/TypeScript/CodeClassDeclarationWriter.cs b/src/Kiota.Builder/Writers/TypeScript/CodeClassDeclarationWriter.cs index 565bd2e5ee..7a669270dc 100644 --- a/src/Kiota.Builder/Writers/TypeScript/CodeClassDeclarationWriter.cs +++ b/src/Kiota.Builder/Writers/TypeScript/CodeClassDeclarationWriter.cs @@ -21,7 +21,7 @@ public override void WriteCodeElement(ClassDeclaration codeElement, LanguageWrit var inheritSymbol = conventions.GetTypeString(codeElement.Inherits, codeElement); var derivation = (inheritSymbol == null ? string.Empty : $" extends {inheritSymbol}") + (!codeElement.Implements.Any() ? string.Empty : $" implements {codeElement.Implements.Select(x => x.Name).Aggregate((x,y) => x + ", " + y)}"); - conventions.WriteShortDescription((codeElement.Parent as CodeClass).Description, writer); + conventions.WriteShortDescription((codeElement.Parent as CodeClass).Documentation.Description, writer); writer.WriteLine($"export class {codeElement.Name.ToFirstCharacterUpperCase()}{derivation} {{"); writer.IncreaseIndent(); } diff --git a/src/Kiota.Builder/Writers/TypeScript/CodeEnumWriter.cs b/src/Kiota.Builder/Writers/TypeScript/CodeEnumWriter.cs index 978e2ed792..2c77b15be4 100644 --- a/src/Kiota.Builder/Writers/TypeScript/CodeEnumWriter.cs +++ b/src/Kiota.Builder/Writers/TypeScript/CodeEnumWriter.cs @@ -12,11 +12,11 @@ public override void WriteCodeElement(CodeEnum codeElement, LanguageWriter write if(!codeElement.Options.Any()) return; - conventions.WriteShortDescription(codeElement.Description, writer); + conventions.WriteShortDescription(codeElement.Documentation.Description, writer); writer.WriteLine($"export enum {codeElement.Name.ToFirstCharacterUpperCase()} {{"); writer.IncreaseIndent(); codeElement.Options.ToList().ForEach(x => { - conventions.WriteShortDescription(x.Description, writer); + conventions.WriteShortDescription(x.Documentation.Description, writer); writer.WriteLine($"{x.Name.ToFirstCharacterUpperCase()} = \"{x.SerializationName ?? x.Name}\","); }); } diff --git a/src/Kiota.Builder/Writers/TypeScript/CodeMethodWriter.cs b/src/Kiota.Builder/Writers/TypeScript/CodeMethodWriter.cs index 3d6a3dc820..a9d60f7736 100644 --- a/src/Kiota.Builder/Writers/TypeScript/CodeMethodWriter.cs +++ b/src/Kiota.Builder/Writers/TypeScript/CodeMethodWriter.cs @@ -342,14 +342,14 @@ private void WriteSerializerBody(bool inherits, CodeClass parentClass, LanguageW writer.WriteLine($"writer.writeAdditionalData(this.{additionalDataProperty.Name.ToFirstCharacterLowerCase()});"); } private void WriteMethodDocumentation(CodeMethod code, LanguageWriter writer, bool isVoid) { - var isDescriptionPresent = !string.IsNullOrEmpty(code.Description); - var parametersWithDescription = code.Parameters.Where(x => !string.IsNullOrEmpty(code.Description)); + var isDescriptionPresent = !string.IsNullOrEmpty(code.Documentation.Description); + var parametersWithDescription = code.Parameters.Where(x => !string.IsNullOrEmpty(code.Documentation.Description)); if (isDescriptionPresent || parametersWithDescription.Any()) { writer.WriteLine(localConventions.DocCommentStart); if(isDescriptionPresent) - writer.WriteLine($"{localConventions.DocCommentPrefix}{TypeScriptConventionService.RemoveInvalidDescriptionCharacters(code.Description)}"); + writer.WriteLine($"{localConventions.DocCommentPrefix}{TypeScriptConventionService.RemoveInvalidDescriptionCharacters(code.Documentation.Description)}"); foreach(var paramWithDescription in parametersWithDescription.OrderBy(x => x.Name)) - writer.WriteLine($"{localConventions.DocCommentPrefix}@param {paramWithDescription.Name} {TypeScriptConventionService.RemoveInvalidDescriptionCharacters(paramWithDescription.Description)}"); + writer.WriteLine($"{localConventions.DocCommentPrefix}@param {paramWithDescription.Name} {TypeScriptConventionService.RemoveInvalidDescriptionCharacters(paramWithDescription.Documentation.Description)}"); if(!isVoid) if(code.IsAsync) diff --git a/src/Kiota.Builder/Writers/TypeScript/CodePropertyWriter.cs b/src/Kiota.Builder/Writers/TypeScript/CodePropertyWriter.cs index 503c0158ba..cb0b48bc5e 100644 --- a/src/Kiota.Builder/Writers/TypeScript/CodePropertyWriter.cs +++ b/src/Kiota.Builder/Writers/TypeScript/CodePropertyWriter.cs @@ -10,7 +10,7 @@ public override void WriteCodeElement(CodeProperty codeElement, LanguageWriter w var returnType = conventions.GetTypeString(codeElement.Type, codeElement); var isFlagEnum = codeElement.Type is CodeType currentType && currentType.TypeDefinition is CodeEnum currentEnum && currentEnum.Flags; var parentClass = codeElement.Parent as CodeClass; - conventions.WriteShortDescription(codeElement.Description, writer); + conventions.WriteShortDescription(codeElement.Documentation.Description, writer); switch(codeElement.Kind) { case CodePropertyKind.RequestBuilder: writer.WriteLine($"{conventions.GetAccessModifier(codeElement.Access)} get {codeElement.Name.ToFirstCharacterLowerCase()}(): {returnType} {{"); diff --git a/tests/Kiota.Builder.Tests/CodeDOM/CodeEnumTests.cs b/tests/Kiota.Builder.Tests/CodeDOM/CodeEnumTests.cs index 4a71f0de1a..1eb99e173b 100644 --- a/tests/Kiota.Builder.Tests/CodeDOM/CodeEnumTests.cs +++ b/tests/Kiota.Builder.Tests/CodeDOM/CodeEnumTests.cs @@ -11,7 +11,9 @@ public void EnumInits() { var root = CodeNamespace.InitRootNamespace(); var codeEnum = root.AddEnum(new CodeEnum { Name = "Enum", - Description = "some description", + Documentation = new() { + Description = "some description", + }, Flags = true, }).First(); codeEnum.AddOption(new CodeEnumOption { Name = "option1"}); diff --git a/tests/Kiota.Builder.Tests/CodeDOM/CodeIndexerTests.cs b/tests/Kiota.Builder.Tests/CodeDOM/CodeIndexerTests.cs index e3478b5a36..4b382777e0 100644 --- a/tests/Kiota.Builder.Tests/CodeDOM/CodeIndexerTests.cs +++ b/tests/Kiota.Builder.Tests/CodeDOM/CodeIndexerTests.cs @@ -1,18 +1,18 @@ using Kiota.Builder.CodeDOM; - using Xunit; -namespace Kiota.Builder.Tests.CodeDOM { - public class CodeIndexerTests { - [Fact] - public void IndexerInits() { - var indexer = new CodeIndexer { - Name = "idx", - Description = "some description" - }; - indexer.IndexType = new CodeType(); - indexer.ReturnType = new CodeType(); - } +namespace Kiota.Builder.Tests.CodeDOM; +public class CodeIndexerTests { + [Fact] + public void IndexerInits() { + _ = new CodeIndexer + { + Name = "idx", + Documentation = new() { + Description = "some description", + }, + IndexType = new CodeType(), + ReturnType = new CodeType() + }; } - } diff --git a/tests/Kiota.Builder.Tests/KiotaBuilderTests.cs b/tests/Kiota.Builder.Tests/KiotaBuilderTests.cs index 4373c0154d..aee282cc25 100644 --- a/tests/Kiota.Builder.Tests/KiotaBuilderTests.cs +++ b/tests/Kiota.Builder.Tests/KiotaBuilderTests.cs @@ -89,7 +89,7 @@ await File.WriteAllTextAsync(tempFilePath, @"openapi: 3.0.1 var firstOption = enumDef.Options.First(); Assert.Equal("Standard_LRS", firstOption.SerializationName); Assert.Equal("StandardLocalRedundancy", firstOption.Name); - Assert.NotEmpty(firstOption.Description); + Assert.NotEmpty(firstOption.Documentation.Description); File.Delete(tempFilePath); } @@ -3423,7 +3423,7 @@ public void ModelsDoesntUsePathDescriptionWhenAvailable(){ Assert.NotNull(modelsNS); var responseClass = modelsNS.Classes.FirstOrDefault(x => x.IsOfKind(CodeClassKind.Model)); Assert.NotNull(responseClass); - Assert.Null(responseClass.Description); + Assert.Null(responseClass.Documentation.Description); } [Fact] public void CleansUpInvalidDescriptionCharacters(){ @@ -3483,7 +3483,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.Description); + Assert.Equal("some description with invalid characters: ", responseClass.Documentation.Description); } [InlineData("application/json")] [InlineData("application/json;odata.metadata=minimal;odata.streaming=true;IEEE754Compatible=false;charset=utf-8")] @@ -3596,15 +3596,15 @@ public void ModelsUseDescriptionWhenAvailable(){ Assert.NotNull(modelsSubNS); var responseClass = modelsSubNS.Classes.FirstOrDefault(x => x.IsOfKind(CodeClassKind.Model)); Assert.NotNull(responseClass); - Assert.Equal("some description", responseClass.Description); + Assert.Equal("some description", responseClass.Documentation.Description); responseClass = modelsSubNS.Classes.FirstOrDefault(c => c.IsOfKind(CodeClassKind.RequestBuilder)); Assert.NotNull(responseClass); - Assert.Equal("some path item description", responseClass.Description); + Assert.Equal("some path item description", responseClass.Documentation.Description); var responseProperty = codeModel.FindNamespaceByName("TestSdk").Classes.SelectMany(c=> c.Properties).FirstOrDefault(p => p.Kind == CodePropertyKind.RequestBuilder); Assert.NotNull(responseProperty); - Assert.Equal("some path item description", responseProperty.Description); + Assert.Equal("some path item description", responseProperty.Documentation.Description); } [InlineData("application/json", "206", true, "default", "binary")] diff --git a/tests/Kiota.Builder.Tests/Refiners/CSharpLanguageRefinerTests.cs b/tests/Kiota.Builder.Tests/Refiners/CSharpLanguageRefinerTests.cs index 2be62843cd..91d62aeae1 100644 --- a/tests/Kiota.Builder.Tests/Refiners/CSharpLanguageRefinerTests.cs +++ b/tests/Kiota.Builder.Tests/Refiners/CSharpLanguageRefinerTests.cs @@ -242,7 +242,9 @@ public async Task KeepsCancellationParametersInRequestExecutors() Name = "cancelletionToken", Optional = true, Kind = CodeParameterKind.Cancellation, - Description = "Cancellation token to use when cancelling requests", + Documentation = new() { + Description = "Cancellation token to use when cancelling requests", + }, Type = new CodeType { Name = "CancelletionToken", IsExternal = true }, }; method.AddParameter(cancellationParam); diff --git a/tests/Kiota.Builder.Tests/Refiners/GoLanguageRefinerTests.cs b/tests/Kiota.Builder.Tests/Refiners/GoLanguageRefinerTests.cs index 299f28de93..13b9f13157 100644 --- a/tests/Kiota.Builder.Tests/Refiners/GoLanguageRefinerTests.cs +++ b/tests/Kiota.Builder.Tests/Refiners/GoLanguageRefinerTests.cs @@ -320,7 +320,9 @@ public async Task RenamesCancellationParametersInRequestExecutors() Name = "cancelletionToken", Optional = true, Kind = CodeParameterKind.Cancellation, - Description = "Cancellation token to use when cancelling requests", + Documentation = new() { + Description = "Cancellation token to use when cancelling requests", + }, Type = new CodeType { Name = "CancelletionToken", IsExternal = true }, }; method.AddParameter(cancellationParam); diff --git a/tests/Kiota.Builder.Tests/Refiners/JavaLanguageRefinerTests.cs b/tests/Kiota.Builder.Tests/Refiners/JavaLanguageRefinerTests.cs index f20b6a0a0d..c877b10a61 100644 --- a/tests/Kiota.Builder.Tests/Refiners/JavaLanguageRefinerTests.cs +++ b/tests/Kiota.Builder.Tests/Refiners/JavaLanguageRefinerTests.cs @@ -274,7 +274,9 @@ public async Task DoesNotKeepCancellationParametersInRequestExecutors() Name = "cancelletionToken", Optional = true, Kind = CodeParameterKind.Cancellation, - Description = "Cancellation token to use when cancelling requests", + Documentation = new() { + Description = "Cancellation token to use when cancelling requests", + }, Type = new CodeType { Name = "CancelletionToken", IsExternal = true }, }; method.AddParameter(cancellationParam); diff --git a/tests/Kiota.Builder.Tests/Refiners/PythonLanguageRefinerTests.cs b/tests/Kiota.Builder.Tests/Refiners/PythonLanguageRefinerTests.cs index eea808d539..81148feb09 100644 --- a/tests/Kiota.Builder.Tests/Refiners/PythonLanguageRefinerTests.cs +++ b/tests/Kiota.Builder.Tests/Refiners/PythonLanguageRefinerTests.cs @@ -311,7 +311,9 @@ public async Task DoesNotKeepCancellationParametersInRequestExecutors() Name = "cancellationToken", Optional = true, Kind = CodeParameterKind.Cancellation, - Description = "Cancellation token to use when cancelling requests", + Documentation = new() { + Description = "Cancellation token to use when cancelling requests", + }, Type = new CodeType { Name = "CancellationToken", IsExternal = true }, }; method.AddParameter(cancellationParam); diff --git a/tests/Kiota.Builder.Tests/Refiners/RubyLanguageRefinerTests.cs b/tests/Kiota.Builder.Tests/Refiners/RubyLanguageRefinerTests.cs index 5336bc85b4..c7c28de7c0 100644 --- a/tests/Kiota.Builder.Tests/Refiners/RubyLanguageRefinerTests.cs +++ b/tests/Kiota.Builder.Tests/Refiners/RubyLanguageRefinerTests.cs @@ -44,7 +44,9 @@ public async Task DoesNotKeepCancellationParametersInRequestExecutors() Name = "cancellationToken", Optional = true, Kind = CodeParameterKind.Cancellation, - Description = "Cancellation token to use when cancelling requests", + Documentation = new (){ + Description = "Cancellation token to use when cancelling requests", + }, Type = new CodeType { Name = "CancellationToken", IsExternal = true }, }; method.AddParameter(cancellationParam); diff --git a/tests/Kiota.Builder.Tests/Refiners/TypeScriptLanguageRefinerTests.cs b/tests/Kiota.Builder.Tests/Refiners/TypeScriptLanguageRefinerTests.cs index 1f4e34f195..dc1d0c7cc0 100644 --- a/tests/Kiota.Builder.Tests/Refiners/TypeScriptLanguageRefinerTests.cs +++ b/tests/Kiota.Builder.Tests/Refiners/TypeScriptLanguageRefinerTests.cs @@ -421,7 +421,9 @@ public async Task DoesNotKeepCancellationParametersInRequestExecutors() Name = "cancelletionToken", Optional = true, Kind = CodeParameterKind.Cancellation, - Description = "Cancellation token to use when cancelling requests", + Documentation = new() { + Description = "Cancellation token to use when cancelling requests", + }, Type = new CodeType { Name = "CancelletionToken", IsExternal = true }, }; method.AddParameter(cancellationParam); diff --git a/tests/Kiota.Builder.Tests/Writers/CSharp/CodeEnumWriterTests.cs b/tests/Kiota.Builder.Tests/Writers/CSharp/CodeEnumWriterTests.cs index 7e966af12f..188019db79 100644 --- a/tests/Kiota.Builder.Tests/Writers/CSharp/CodeEnumWriterTests.cs +++ b/tests/Kiota.Builder.Tests/Writers/CSharp/CodeEnumWriterTests.cs @@ -53,11 +53,11 @@ public void WritesFlagsEnum() { } [Fact] public void WritesEnumOptionDescription() { - Option.Description = "Some option description"; + Option.Documentation.Description = "Some option description"; currentEnum.AddOption(Option); writer.Write(currentEnum); var result = tw.ToString(); - Assert.Contains($"{Option.Description}", result); + Assert.Contains($"{Option.Documentation.Description}", result); AssertExtensions.CurlyBracesAreClosed(result, 1); } [Fact] diff --git a/tests/Kiota.Builder.Tests/Writers/CSharp/CodeMethodWriterTests.cs b/tests/Kiota.Builder.Tests/Writers/CSharp/CodeMethodWriterTests.cs index ac0bf2c903..6d42d1fae8 100644 --- a/tests/Kiota.Builder.Tests/Writers/CSharp/CodeMethodWriterTests.cs +++ b/tests/Kiota.Builder.Tests/Writers/CSharp/CodeMethodWriterTests.cs @@ -870,13 +870,17 @@ public void WritesSerializerBody() { [Fact] public void WritesMethodAsyncDescription() { - method.Description = MethodDescription; - var parameter = new CodeParameter{ - Description = ParamDescription, - Name = ParamName - }; - parameter.Type = new CodeType { - Name = "string" + method.Documentation.Description = MethodDescription; + var parameter = new CodeParameter + { + Documentation = new() { + Description = ParamDescription + }, + Name = ParamName, + Type = new CodeType + { + Name = "string" + } }; method.AddParameter(parameter); writer.Write(method); @@ -893,14 +897,18 @@ public void WritesMethodAsyncDescription() { [Fact] public void WritesMethodSyncDescription() { - method.Description = MethodDescription; + method.Documentation.Description = MethodDescription; method.IsAsync = false; - var parameter = new CodeParameter{ - Description = ParamDescription, - Name = ParamName - }; - parameter.Type = new CodeType { - Name = "string" + var parameter = new CodeParameter + { + Documentation = new() { + Description = ParamDescription + }, + Name = ParamName, + Type = new CodeType + { + Name = "string" + } }; method.AddParameter(parameter); writer.Write(method); diff --git a/tests/Kiota.Builder.Tests/Writers/Go/CodeEnumWriterTests.cs b/tests/Kiota.Builder.Tests/Writers/Go/CodeEnumWriterTests.cs index a93e0c0101..cee98da615 100644 --- a/tests/Kiota.Builder.Tests/Writers/Go/CodeEnumWriterTests.cs +++ b/tests/Kiota.Builder.Tests/Writers/Go/CodeEnumWriterTests.cs @@ -71,13 +71,15 @@ public void WritesUsing() { [Fact] public void WritesEnumOptionDescription() { var option = new CodeEnumOption { - Description = "Some option description", + Documentation = new() { + Description = "Some option description", + }, Name = "option1", }; currentEnum.AddOption(option); writer.Write(currentEnum); var result = tw.ToString(); - Assert.Contains($"// {option.Description}", result); + Assert.Contains($"// {option.Documentation.Description}", result); AssertExtensions.CurlyBracesAreClosed(result); } } diff --git a/tests/Kiota.Builder.Tests/Writers/Go/CodeMethodWriterTests.cs b/tests/Kiota.Builder.Tests/Writers/Go/CodeMethodWriterTests.cs index 69e5469b75..750e3219f8 100644 --- a/tests/Kiota.Builder.Tests/Writers/Go/CodeMethodWriterTests.cs +++ b/tests/Kiota.Builder.Tests/Writers/Go/CodeMethodWriterTests.cs @@ -1140,11 +1140,13 @@ public void WritesSerializerBody() { } [Fact(Skip = "descriptions are not supported")] public void WritesMethodSyncDescription() { - method.Description = MethodDescription; + method.Documentation.Description = MethodDescription; method.IsAsync = false; var parameter = new CodeParameter { - Description = ParamDescription, + Documentation = new() { + Description = ParamDescription + }, Name = ParamName, Type = new CodeType { @@ -1276,7 +1278,7 @@ public void WritesDescription() { Name = "string" } }); - method.Description = "Some description"; + method.Documentation.Description = "Some description"; writer.Write(method); var result = tw.ToString(); Assert.Contains($"// {method.Name.ToFirstCharacterUpperCase()} some description", result); diff --git a/tests/Kiota.Builder.Tests/Writers/Java/CodeEnumWriterTests.cs b/tests/Kiota.Builder.Tests/Writers/Java/CodeEnumWriterTests.cs index fef7506b8b..4b2e712157 100644 --- a/tests/Kiota.Builder.Tests/Writers/Java/CodeEnumWriterTests.cs +++ b/tests/Kiota.Builder.Tests/Writers/Java/CodeEnumWriterTests.cs @@ -56,13 +56,15 @@ public void DoesntWriteAnythingOnNoOption() { [Fact] public void WritesEnumOptionDescription() { var option = new CodeEnumOption { - Description = "Some option description", + Documentation = new() { + Description = "Some option description", + }, Name = "option1", }; currentEnum.AddOption(option); writer.Write(currentEnum); var result = tw.ToString(); - Assert.Contains($"/** {option.Description} */", result); + Assert.Contains($"/** {option.Documentation.Description} */", result); AssertExtensions.CurlyBracesAreClosed(result); } } diff --git a/tests/Kiota.Builder.Tests/Writers/Java/CodeMethodWriterTests.cs b/tests/Kiota.Builder.Tests/Writers/Java/CodeMethodWriterTests.cs index 2a91a0e463..66eb9787ed 100644 --- a/tests/Kiota.Builder.Tests/Writers/Java/CodeMethodWriterTests.cs +++ b/tests/Kiota.Builder.Tests/Writers/Java/CodeMethodWriterTests.cs @@ -1161,13 +1161,17 @@ public void WritesSerializerBody() { [Fact] public void WritesMethodAsyncDescription() { - method.Description = MethodDescription; - var parameter = new CodeParameter{ - Description = ParamDescription, - Name = ParamName - }; - parameter.Type = new CodeType { - Name = "string" + method.Documentation.Description = MethodDescription; + var parameter = new CodeParameter + { + Documentation = new() { + Description = ParamDescription, + }, + Name = ParamName, + Type = new CodeType + { + Name = "string" + } }; method.AddParameter(parameter); writer.Write(method); @@ -1184,14 +1188,18 @@ public void WritesMethodAsyncDescription() { [Fact] public void WritesMethodSyncDescription() { - method.Description = MethodDescription; + method.Documentation.Description = MethodDescription; method.IsAsync = false; - var parameter = new CodeParameter{ - Description = ParamDescription, - Name = ParamName - }; - parameter.Type = new CodeType { - Name = "string" + var parameter = new CodeParameter + { + Documentation = new() { + Description = ParamDescription, + }, + Name = ParamName, + Type = new CodeType + { + Name = "string" + } }; method.AddParameter(parameter); writer.Write(method); diff --git a/tests/Kiota.Builder.Tests/Writers/Php/CodeMethodWriterTests.cs b/tests/Kiota.Builder.Tests/Writers/Php/CodeMethodWriterTests.cs index 861a4d8cd5..b946e0e6ce 100644 --- a/tests/Kiota.Builder.Tests/Writers/Php/CodeMethodWriterTests.cs +++ b/tests/Kiota.Builder.Tests/Writers/Php/CodeMethodWriterTests.cs @@ -48,11 +48,13 @@ public CodeMethodWriterTests() { Name = MethodName, IsAsync = true, - Description = "This is a very good method to try all the good things" - }; - method.ReturnType = new CodeType - { - Name = ReturnTypeName + Documentation = new() { + Description = "This is a very good method to try all the good things", + }, + ReturnType = new CodeType + { + Name = ReturnTypeName + } }; _refiner = new PhpRefiner(new GenerationConfiguration {Language = GenerationLanguage.PHP}); parentClass.AddMethod(method); @@ -67,7 +69,9 @@ private void AddRequestProperties() Name = "urlTemplate", Access = AccessModifier.Protected, DefaultValue = "https://graph.microsoft.com/v1.0/", - Description = "The URL template", + Documentation = new() { + Description = "The URL template", + }, Kind = CodePropertyKind.UrlTemplate, Type = new CodeType {Name = "string"} }, @@ -76,7 +80,9 @@ private void AddRequestProperties() Name = "pathParameters", Access = AccessModifier.Protected, DefaultValue = "[]", - Description = "The Path parameters.", + Documentation = new() { + Description = "The Path parameters.", + }, Kind = CodePropertyKind.PathParameters, Type = new CodeType {Name = "array"} }, @@ -84,7 +90,9 @@ private void AddRequestProperties() { Name = "requestAdapter", Access = AccessModifier.Protected, - Description = "The request Adapter", + Documentation = new() { + Description = "The request Adapter", + }, Kind = CodePropertyKind.RequestAdapter, Type = new CodeType { @@ -163,7 +171,7 @@ public void WriteABasicMethod() [Fact] public void WriteMethodWithNoDescription() { - method.Description = null; + method.Documentation.Description = null; _codeMethodWriter.WriteCodeElement(method, languageWriter); var result = stringWriter.ToString(); @@ -195,7 +203,9 @@ public void WriteRequestExecutor() IsExternal = true, Name = "StreamInterface" }, - Description = "This will send a POST request", + Documentation = new() { + Description = "This will send a POST request", + }, Kind = CodeMethodKind.RequestExecutor }; codeMethod.AddParameter(new CodeParameter @@ -263,7 +273,10 @@ public void WriteRequestExecutor() { new CodeProperty { Name = "status", Type = new CodeType { Name = "Status", TypeDefinition = new CodeEnum { - Name = "Status", Description = "Status Enum" + Name = "Status", + Documentation = new() { + Description = "Status Enum", + }, }}, Access = AccessModifier.Private }, "$writer->writeEnumValue('status', $this->getStatus());" }, @@ -271,7 +284,11 @@ public void WriteRequestExecutor() { new CodeProperty { Name = "architectures", Type = new CodeType { - Name = "Architecture", CollectionKind = CodeTypeBase.CodeTypeCollectionKind.Array, TypeDefinition = new CodeEnum { Name = "Architecture", Description = "Arch Enum, accepts x64, x86, hybrid"} + Name = "Architecture", CollectionKind = CodeTypeBase.CodeTypeCollectionKind.Array, TypeDefinition = new CodeEnum { Name = "Architecture", + Documentation = new() { + Description = "Arch Enum, accepts x64, x86, hybrid" + }, + } }, Access = AccessModifier.Private, Kind = CodePropertyKind.Custom }, "$writer->writeCollectionOfEnumValues('architectures', $this->getArchitectures());" }, @@ -494,7 +511,9 @@ public async Task WriteIndexerBody() Name = "messageById", Access = AccessModifier.Public, Kind = CodeMethodKind.IndexerBackwardCompatibility, - Description = "Get messages by a specific ID.", + Documentation = new() { + Description = "Get messages by a specific ID.", + }, OriginalIndexer = new CodeIndexer { Name = "messageById", @@ -585,7 +604,10 @@ public async Task WriteIndexerBody() { Name = "EmailAddress", TypeDefinition = new CodeClass { - Name = "EmailAddress", Kind = CodeClassKind.Model, Description = "Email", Parent = GetParentClassInStaticContext() + Name = "EmailAddress", Kind = CodeClassKind.Model, + Documentation = new() { + Description = "Email", + }, Parent = GetParentClassInStaticContext() }, CollectionKind = CodeTypeBase.CodeTypeCollectionKind.Array }, Access = AccessModifier.Private}, "'users' => fn(ParseNode $n) => $o->setUsers($n->getCollectionOfObjectValues([EmailAddress::class, 'createFromDiscriminatorValue']))," }, @@ -611,7 +633,9 @@ public async Task WriteDeserializer(CodeProperty property, string expected) { Name = "getDeserializationFields", Kind = CodeMethodKind.Deserializer, - Description = "Just some random method", + Documentation = new() { + Description = "Just some random method", + }, ReturnType = new CodeType { IsNullable = false, @@ -656,7 +680,9 @@ public async Task WriteDeserializerMergeWhenHasParent() { Name = "getDeserializationFields", Kind = CodeMethodKind.Deserializer, - Description = "Just some random method", + Documentation = new() { + Description = "Just some random method", + }, ReturnType = new CodeType { IsNullable = false, @@ -691,7 +717,9 @@ public void WriteConstructorBody() { Name = "constructor", Access = AccessModifier.Public, - Description = "The constructor for this class", + Documentation = new() { + Description = "The constructor for this class", + }, ReturnType = new CodeType {Name = "void"}, Kind = CodeMethodKind.Constructor }; @@ -718,7 +746,9 @@ public void WriteGetter() var getter = new CodeMethod { Name = "getEmailAddress", - Description = "This method gets the emailAddress", + Documentation = new() { + Description = "This method gets the emailAddress", + }, ReturnType = new CodeType { Name = "emailAddress", @@ -745,7 +775,9 @@ public void WriteGetterAdditionalData() var getter = new CodeMethod { Name = "getAdditionalData", - Description = "This method gets the emailAddress", + Documentation = new() { + Description = "This method gets the emailAddress", + }, ReturnType = new CodeType { Name = "additionalData", @@ -1007,7 +1039,9 @@ public async void WritesApiClientWithBackingStoreConstructor() { Name = "backingStore", Optional = true, - Description = "The backing store to use for the models.", + Documentation = new(){ + Description = "The backing store to use for the models.", + }, Kind = CodeParameterKind.BackingStore, Type = new CodeType { @@ -1053,7 +1087,9 @@ public async void WritesModelWithBackingStoreConstructor() { Name = "constructor", Access = AccessModifier.Public, - Description = "The constructor for this class", + Documentation = new() { + Description = "The constructor for this class", + }, ReturnType = new CodeType {Name = "void"}, Kind = CodeMethodKind.Constructor }; diff --git a/tests/Kiota.Builder.Tests/Writers/Php/CodePropertyWriterTests.cs b/tests/Kiota.Builder.Tests/Writers/Php/CodePropertyWriterTests.cs index b65479b168..5bb6dc8fb9 100644 --- a/tests/Kiota.Builder.Tests/Writers/Php/CodePropertyWriterTests.cs +++ b/tests/Kiota.Builder.Tests/Writers/Php/CodePropertyWriterTests.cs @@ -28,7 +28,11 @@ public CodePropertyWriterTests() languageWriter.SetTextWriter(stringWriter); parentClass = new CodeClass { - Name = "ParentClass", Description = "This is an amazing class", Kind = CodeClassKind.Model + Name = "ParentClass", + Documentation = new() { + Description = "This is an amazing class", + }, + Kind = CodeClassKind.Model }; root.AddClass(parentClass); propertyWriter = new CodePropertyWriter(new PhpConventionService()); @@ -60,7 +64,9 @@ public void WritePropertyRequestBuilder() { Name = "message", Access = AccessModifier.Public, - Description = "I can get your messages.", + Documentation = new() { + Description = "I can get your messages.", + }, Type = new CodeType { Name = "MessageRequestBuilder" @@ -80,7 +86,9 @@ public async Task WriteCollectionKindProperty() { var property = new CodeProperty { - Description = "Additional data dictionary", + Documentation = new() { + Description = "Additional data dictionary", + }, Name = "additionalData", Kind = CodePropertyKind.AdditionalData, Access = AccessModifier.Private, diff --git a/tests/Kiota.Builder.Tests/Writers/Python/CodeMethodWriterTests.cs b/tests/Kiota.Builder.Tests/Writers/Python/CodeMethodWriterTests.cs index f5e64afe09..a0bdf84055 100644 --- a/tests/Kiota.Builder.Tests/Writers/Python/CodeMethodWriterTests.cs +++ b/tests/Kiota.Builder.Tests/Writers/Python/CodeMethodWriterTests.cs @@ -359,13 +359,17 @@ public void WritesSerializerBody() { [Fact] public void WritesMethodAsyncDescription() { - method.Description = MethodDescription; - var parameter = new CodeParameter{ - Description = ParamDescription, - Name = ParamName - }; - parameter.Type = new CodeType { - Name = "string" + method.Documentation.Description = MethodDescription; + var parameter = new CodeParameter + { + Documentation = new() { + Description = ParamDescription, + }, + Name = ParamName, + Type = new CodeType + { + Name = "string" + } }; method.AddParameter(parameter); writer.Write(method); @@ -381,14 +385,18 @@ public void WritesMethodAsyncDescription() { [Fact] public void WritesMethodSyncDescription() { - method.Description = MethodDescription; + method.Documentation.Description = MethodDescription; method.IsAsync = false; - var parameter = new CodeParameter{ - Description = ParamDescription, - Name = ParamName - }; - parameter.Type = new CodeType { - Name = "string" + var parameter = new CodeParameter + { + Documentation = new() { + Description = ParamDescription, + }, + Name = ParamName, + Type = new CodeType + { + Name = "string" + } }; method.AddParameter(parameter); writer.Write(method); @@ -586,7 +594,9 @@ public void WritesConstructor() { Name = propName, DefaultValue = defaultValue, Kind = CodePropertyKind.UrlTemplate, - Description = "This property has a description", + Documentation = new() { + Description = "This property has a description", + }, Type = new CodeType { Name = "string" } @@ -617,7 +627,9 @@ public void WritesConstructorWithInheritance() { parentClass.AddProperty(new CodeProperty { Name = propName, Kind = CodePropertyKind.Custom, - Description = "This property has a description", + Documentation = new() { + Description = "This property has a description", + }, Type = new CodeType { Name = "string" } @@ -629,7 +641,9 @@ public void WritesConstructorWithInheritance() { Name = prop2Name, DefaultValue = defaultValue, Kind = CodePropertyKind.UrlTemplate, - Description = "This property has a description", + Documentation = new() { + Description = "This property has a description", + }, Type = new CodeType { Name = "string" } diff --git a/tests/Kiota.Builder.Tests/Writers/Python/CodePropertyWriterTests.cs b/tests/Kiota.Builder.Tests/Writers/Python/CodePropertyWriterTests.cs index f87bb40882..6f52765eb2 100644 --- a/tests/Kiota.Builder.Tests/Writers/Python/CodePropertyWriterTests.cs +++ b/tests/Kiota.Builder.Tests/Writers/Python/CodePropertyWriterTests.cs @@ -46,7 +46,7 @@ public void Dispose() { [Fact] public void WritesRequestBuilder() { property.Kind = CodePropertyKind.RequestBuilder; - property.Description = "This is a request builder"; + property.Documentation.Description = "This is a request builder"; writer.Write(property); var result = tw.ToString(); Assert.Contains("def property_name(", result); diff --git a/tests/Kiota.Builder.Tests/Writers/Ruby/CodeMethodWriterTests.cs b/tests/Kiota.Builder.Tests/Writers/Ruby/CodeMethodWriterTests.cs index 9ffb93e02a..ec59ab95d2 100644 --- a/tests/Kiota.Builder.Tests/Writers/Ruby/CodeMethodWriterTests.cs +++ b/tests/Kiota.Builder.Tests/Writers/Ruby/CodeMethodWriterTests.cs @@ -227,13 +227,6 @@ public void WritesInheritedDeSerializerBody() { } [Fact] public void WritesDeSerializerBody() { - var parameter = new CodeParameter{ - Description = ParamDescription, - Name = ParamName - }; - parameter.Type = new CodeType { - Name = "string" - }; method.Kind = CodeMethodKind.Deserializer; method.IsAsync = false; AddSerializationProperties(); @@ -256,13 +249,6 @@ public void WritesInheritedSerializerBody() { } [Fact] public void WritesSerializerBody() { - var parameter = new CodeParameter{ - Description = ParamDescription, - Name = ParamName - }; - parameter.Type = new CodeType { - Name = "string" - }; method.Kind = CodeMethodKind.Serializer; method.IsAsync = false; AddSerializationProperties(); @@ -333,14 +319,18 @@ public void WritesTranslatedTypesDeSerializerBody() { [Fact] public void WritesMethodSyncDescription() { - method.Description = MethodDescription; + method.Documentation.Description = MethodDescription; method.IsAsync = false; - var parameter = new CodeParameter { - Description = ParamDescription, - Name = ParamName - }; - parameter.Type = new CodeType { - Name = "string" + var parameter = new CodeParameter + { + Documentation = new() { + Description = ParamDescription, + }, + Name = ParamName, + Type = new CodeType + { + Name = "string" + } }; method.AddParameter(parameter); writer.Write(method); diff --git a/tests/Kiota.Builder.Tests/Writers/Shell/ShellCodeMethodWriterTests.cs b/tests/Kiota.Builder.Tests/Writers/Shell/ShellCodeMethodWriterTests.cs index e633db7ca8..c5011b44f9 100644 --- a/tests/Kiota.Builder.Tests/Writers/Shell/ShellCodeMethodWriterTests.cs +++ b/tests/Kiota.Builder.Tests/Writers/Shell/ShellCodeMethodWriterTests.cs @@ -114,7 +114,9 @@ private static void AddPathQueryAndHeaderParameters(CodeMethod method) { Kind = CodeParameterKind.QueryParameter, Type = stringType, DefaultValue = "test", - Description = "The q option", + Documentation = new() { + Description = "The q option", + }, Optional = true }); method.AddPathQueryOrHeaderParameter(new CodeParameter { @@ -126,7 +128,9 @@ private static void AddPathQueryAndHeaderParameters(CodeMethod method) { Name = "Test-Header", Kind = CodeParameterKind.Headers, Type = stringType, - Description = "The test header", + Documentation = new() { + Description = "The test header", + }, }); } @@ -304,7 +308,7 @@ public void WritesExecutableCommandForGetRequestPrimitive() { method.Kind = CodeMethodKind.CommandBuilder; - method.Description = "Test description"; + method.Documentation.Description = "Test description"; method.SimpleName = "User"; method.HttpMethod = HttpMethod.Get; var stringType = new CodeType @@ -371,7 +375,7 @@ public void WritesExecutableCommandForPagedGetRequestModel() { method.Kind = CodeMethodKind.CommandBuilder; - method.Description = "Test description"; + method.Documentation.Description = "Test description"; method.SimpleName = "User"; method.HttpMethod = HttpMethod.Get; var userClass = root.AddClass(new CodeClass @@ -445,7 +449,7 @@ public void WritesExecutableCommandForGetRequestModel() { method.Kind = CodeMethodKind.CommandBuilder; - method.Description = "Test description"; + method.Documentation.Description = "Test description"; method.SimpleName = "User"; method.HttpMethod = HttpMethod.Get; var userClass = root.AddClass(new CodeClass diff --git a/tests/Kiota.Builder.Tests/Writers/TypeScript/CodeEnumWriterTests.cs b/tests/Kiota.Builder.Tests/Writers/TypeScript/CodeEnumWriterTests.cs index 54108464af..80ee4f6611 100644 --- a/tests/Kiota.Builder.Tests/Writers/TypeScript/CodeEnumWriterTests.cs +++ b/tests/Kiota.Builder.Tests/Writers/TypeScript/CodeEnumWriterTests.cs @@ -47,13 +47,15 @@ public void DoesntWriteAnythingOnNoOption() { [Fact] public void WritesEnumOptionDescription() { var option = new CodeEnumOption { - Description = "Some option description", + Documentation = new() { + Description = "Some option description", + }, Name = "option1", }; currentEnum.AddOption(option); writer.Write(currentEnum); var result = tw.ToString(); - Assert.Contains($"/** {option.Description} */", result); + Assert.Contains($"/** {option.Documentation.Description} */", result); AssertExtensions.CurlyBracesAreClosed(result, 1); } } diff --git a/tests/Kiota.Builder.Tests/Writers/TypeScript/CodeMethodWriterTests.cs b/tests/Kiota.Builder.Tests/Writers/TypeScript/CodeMethodWriterTests.cs index c1bc8b4c9c..be4237cd11 100644 --- a/tests/Kiota.Builder.Tests/Writers/TypeScript/CodeMethodWriterTests.cs +++ b/tests/Kiota.Builder.Tests/Writers/TypeScript/CodeMethodWriterTests.cs @@ -371,13 +371,17 @@ public void WritesSerializerBody() { [Fact] public void WritesMethodAsyncDescription() { - method.Description = MethodDescription; - var parameter = new CodeParameter{ - Description = ParamDescription, - Name = ParamName - }; - parameter.Type = new CodeType { - Name = "string" + method.Documentation.Description = MethodDescription; + var parameter = new CodeParameter + { + Documentation = new() { + Description = ParamDescription, + }, + Name = ParamName, + Type = new CodeType + { + Name = "string" + } }; method.AddParameter(parameter); writer.Write(method); @@ -394,14 +398,18 @@ public void WritesMethodAsyncDescription() { [Fact] public void WritesMethodSyncDescription() { - method.Description = MethodDescription; + method.Documentation.Description = MethodDescription; method.IsAsync = false; - var parameter = new CodeParameter{ - Description = ParamDescription, - Name = ParamName - }; - parameter.Type = new CodeType { - Name = "string" + var parameter = new CodeParameter + { + Documentation = new() { + Description = ParamDescription, + }, + Name = ParamName, + Type = new CodeType + { + Name = "string" + } }; method.AddParameter(parameter); writer.Write(method); From 164bd382e95fe0d7998997e4a8a10516c5f4e185 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Wed, 7 Dec 2022 11:35:50 -0500 Subject: [PATCH 03/12] - adds a default placeholder for request body description Signed-off-by: Vincent Biret --- src/Kiota.Builder/KiotaBuilder.cs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/Kiota.Builder/KiotaBuilder.cs b/src/Kiota.Builder/KiotaBuilder.cs index be45d715a5..32830f0190 100644 --- a/src/Kiota.Builder/KiotaBuilder.cs +++ b/src/Kiota.Builder/KiotaBuilder.cs @@ -849,9 +849,9 @@ private void CreateOperationMethods(OpenApiUrlTreeNode currentNode, OperationTyp executorMethod.ReturnType = returnType ?? throw new InvalidOperationException("Could not resolve return type for operation"); } else { string returnType; - if(operation.Responses.Any(x => noContentStatusCodes.Contains(x.Key))) + if(operation.Responses.Any(static x => noContentStatusCodes.Contains(x.Key))) returnType = voidType; - else if (operation.Responses.Any(x => x.Value.Content.ContainsKey(RequestBodyPlainTextContentType))) + else if (operation.Responses.Any(static x => x.Value.Content.ContainsKey(RequestBodyPlainTextContentType))) returnType = "string"; else returnType = "binary"; @@ -982,7 +982,7 @@ private void AddRequestBuilderMethodParameters(OpenApiUrlTreeNode currentNode, O Optional = false, Kind = CodeParameterKind.RequestBody, Documentation = new() { - Description = requestBodySchema.Description.CleanupDescription() + Description = requestBodySchema.Description.CleanupDescription() ?? "The request body" }, }); method.RequestBodyContentType = operation.RequestBody.Content.First(x => x.Value.Schema == requestBodySchema).Key; From 589f579dfaa24dc549ffdb0b56bf4221eab82469 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Wed, 7 Dec 2022 11:38:49 -0500 Subject: [PATCH 04/12] - adds support for documentation link in CSharp Signed-off-by: Vincent Biret --- .../CodeDOM/CodeDocumentation.cs | 2 ++ .../Writers/CSharp/CodeMethodWriter.cs | 11 +++++---- .../Writers/CSharp/CodeMethodWriterTests.cs | 24 +++++++++++++++++++ 3 files changed, 32 insertions(+), 5 deletions(-) diff --git a/src/Kiota.Builder/CodeDOM/CodeDocumentation.cs b/src/Kiota.Builder/CodeDOM/CodeDocumentation.cs index 374472e268..5ea9d93ad9 100644 --- a/src/Kiota.Builder/CodeDOM/CodeDocumentation.cs +++ b/src/Kiota.Builder/CodeDOM/CodeDocumentation.cs @@ -39,4 +39,6 @@ public object Clone() DocumentationLabel = DocumentationLabel?.Clone() as string, }; } + public bool DescriptionAvailable { get => !string.IsNullOrEmpty(Description); } + public bool ExternalDocumentationAvailable { get => DocumentationLink != null && !string.IsNullOrEmpty(DocumentationLabel); } } diff --git a/src/Kiota.Builder/Writers/CSharp/CodeMethodWriter.cs b/src/Kiota.Builder/Writers/CSharp/CodeMethodWriter.cs index 4330bbcdc4..42de7b9952 100644 --- a/src/Kiota.Builder/Writers/CSharp/CodeMethodWriter.cs +++ b/src/Kiota.Builder/Writers/CSharp/CodeMethodWriter.cs @@ -525,15 +525,16 @@ protected string GetSendRequestMethodName(bool isVoid, CodeElement currentElemen } 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)); - if (isDescriptionPresent || parametersWithDescription.Any()) + var parametersWithDescription = code.Parameters.Where(static x => !string.IsNullOrEmpty(x.Documentation.Description)); + if (code.Documentation.DescriptionAvailable || parametersWithDescription.Any()) { writer.WriteLine($"{conventions.DocCommentPrefix}"); - if (isDescriptionPresent) + if (code.Documentation.DescriptionAvailable) writer.WriteLine($"{conventions.DocCommentPrefix}{code.Documentation.Description.CleanupXMLString()}"); + if(code.Documentation.ExternalDocumentationAvailable) + writer.WriteLine($"{conventions.DocCommentPrefix}{code.Documentation.DocumentationLabel} "); writer.WriteLine($"{conventions.DocCommentPrefix}"); - foreach (var paramWithDescription in parametersWithDescription.OrderBy(x => x.Name)) + foreach (var paramWithDescription in parametersWithDescription.OrderBy(static x => x.Name, StringComparer.OrdinalIgnoreCase)) writer.WriteLine($"{conventions.DocCommentPrefix}{paramWithDescription.Documentation.Description.CleanupXMLString()}"); } } diff --git a/tests/Kiota.Builder.Tests/Writers/CSharp/CodeMethodWriterTests.cs b/tests/Kiota.Builder.Tests/Writers/CSharp/CodeMethodWriterTests.cs index 6d42d1fae8..a7e5a01e92 100644 --- a/tests/Kiota.Builder.Tests/Writers/CSharp/CodeMethodWriterTests.cs +++ b/tests/Kiota.Builder.Tests/Writers/CSharp/CodeMethodWriterTests.cs @@ -917,6 +917,30 @@ public void WritesMethodSyncDescription() { AssertExtensions.CurlyBracesAreClosed(result); } [Fact] + public void WritesMethodDescriptionLink() { + + method.Documentation.Description = MethodDescription; + method.Documentation.DocumentationLabel = "see more"; + method.Documentation.DocumentationLink = new("https://foo.org/docs"); + method.IsAsync = false; + var parameter = new CodeParameter + { + Documentation = new() { + Description = ParamDescription, + }, + Name = ParamName, + Type = new CodeType + { + Name = "string" + } + }; + method.AddParameter(parameter); + writer.Write(method); + var result = tw.ToString(); + Assert.Contains(""); diff --git a/src/Kiota.Builder/Writers/Java/CodeMethodWriter.cs b/src/Kiota.Builder/Writers/Java/CodeMethodWriter.cs index 5246d93efa..df10ae9a30 100644 --- a/src/Kiota.Builder/Writers/Java/CodeMethodWriter.cs +++ b/src/Kiota.Builder/Writers/Java/CodeMethodWriter.cs @@ -633,11 +633,10 @@ private string WriteMethodPrototype(CodeMethod code, LanguageWriter writer, stri return collectionCorrectedReturnType; } 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)); - if (isDescriptionPresent || parametersWithDescription.Any()) { + var parametersWithDescription = code.Parameters.Where(static x => x.Documentation.DescriptionAvailable); + if (code.Documentation.DescriptionAvailable || parametersWithDescription.Any()) { writer.WriteLine(conventions.DocCommentStart); - if(isDescriptionPresent) + if(code.Documentation.DescriptionAvailable) writer.WriteLine($"{conventions.DocCommentPrefix}{JavaConventionService.RemoveInvalidDescriptionCharacters(code.Documentation.Description)}"); foreach(var paramWithDescription in parametersWithDescription.OrderBy(x => x.Name)) writer.WriteLine($"{conventions.DocCommentPrefix}@param {paramWithDescription.Name} {JavaConventionService.RemoveInvalidDescriptionCharacters(paramWithDescription.Documentation.Description)}"); @@ -646,6 +645,9 @@ private void WriteMethodDocumentation(CodeMethod code, LanguageWriter writer) { writer.WriteLine($"{conventions.DocCommentPrefix}@return a CompletableFuture of {code.ReturnType.Name}"); else writer.WriteLine($"{conventions.DocCommentPrefix}@return a {code.ReturnType.Name}"); + + if(code.Documentation.ExternalDocumentationAvailable) + writer.WriteLine($"{conventions.DocCommentPrefix}@see {code.Documentation.DocumentationLabel}"); writer.WriteLine(conventions.DocCommentEnd); } } diff --git a/tests/Kiota.Builder.Tests/Writers/Java/CodeMethodWriterTests.cs b/tests/Kiota.Builder.Tests/Writers/Java/CodeMethodWriterTests.cs index 66eb9787ed..1a6a788d13 100644 --- a/tests/Kiota.Builder.Tests/Writers/Java/CodeMethodWriterTests.cs +++ b/tests/Kiota.Builder.Tests/Writers/Java/CodeMethodWriterTests.cs @@ -1208,6 +1208,29 @@ public void WritesMethodSyncDescription() { AssertExtensions.CurlyBracesAreClosed(result); } [Fact] + public void WritesMethodDescriptionLink() { + method.Documentation.Description = MethodDescription; + method.Documentation.DocumentationLabel = "see more"; + method.Documentation.DocumentationLink = new("https://foo.org/docs"); + method.IsAsync = false; + var parameter = new CodeParameter + { + Documentation = new() { + Description = ParamDescription, + }, + Name = ParamName, + Type = new CodeType + { + Name = "string" + } + }; + method.AddParameter(parameter); + writer.Write(method); + var result = tw.ToString(); + Assert.Contains("@see !string.IsNullOrEmpty(code.Documentation.Description)); - if (isDescriptionPresent || parametersWithDescription.Any()) { + var parametersWithDescription = code.Parameters.Where(static x => x.Documentation.DescriptionAvailable); + if (code.Documentation.DescriptionAvailable || parametersWithDescription.Any()) { writer.WriteLine(localConventions.DocCommentStart); - if(isDescriptionPresent) + if(code.Documentation.DescriptionAvailable) writer.WriteLine($"{localConventions.DocCommentPrefix}{TypeScriptConventionService.RemoveInvalidDescriptionCharacters(code.Documentation.Description)}"); foreach(var paramWithDescription in parametersWithDescription.OrderBy(x => x.Name)) writer.WriteLine($"{localConventions.DocCommentPrefix}@param {paramWithDescription.Name} {TypeScriptConventionService.RemoveInvalidDescriptionCharacters(paramWithDescription.Documentation.Description)}"); @@ -356,6 +355,8 @@ private void WriteMethodDocumentation(CodeMethod code, LanguageWriter writer, bo writer.WriteLine($"{localConventions.DocCommentPrefix}@returns a Promise of {code.ReturnType.Name.ToFirstCharacterUpperCase()}"); else writer.WriteLine($"{localConventions.DocCommentPrefix}@returns a {code.ReturnType.Name}"); + if(code.Documentation.ExternalDocumentationAvailable) + writer.WriteLine($"{localConventions.DocCommentPrefix}@see {{@link {code.Documentation.DocumentationLink}|{code.Documentation.DocumentationLabel}}}"); writer.WriteLine(localConventions.DocCommentEnd); } } diff --git a/tests/Kiota.Builder.Tests/Writers/TypeScript/CodeMethodWriterTests.cs b/tests/Kiota.Builder.Tests/Writers/TypeScript/CodeMethodWriterTests.cs index be4237cd11..887766f20a 100644 --- a/tests/Kiota.Builder.Tests/Writers/TypeScript/CodeMethodWriterTests.cs +++ b/tests/Kiota.Builder.Tests/Writers/TypeScript/CodeMethodWriterTests.cs @@ -418,6 +418,29 @@ public void WritesMethodSyncDescription() { AssertExtensions.CurlyBracesAreClosed(result); } [Fact] + public void WritesMethodDescriptionLink() { + method.Documentation.Description = MethodDescription; + method.Documentation.DocumentationLabel = "see more"; + method.Documentation.DocumentationLink = new("https://foo.org/docs"); + method.IsAsync = false; + var parameter = new CodeParameter + { + Documentation = new() { + Description = ParamDescription, + }, + Name = ParamName, + Type = new CodeType + { + Name = "string" + } + }; + method.AddParameter(parameter); + writer.Write(method); + var result = tw.ToString(); + Assert.Contains("@see {@link", result); + AssertExtensions.CurlyBracesAreClosed(result); + } + [Fact] public void Defensive() { var codeMethodWriter = new CodeMethodWriter(new TypeScriptConventionService(writer), false); Assert.Throws(() => codeMethodWriter.WriteCodeElement(null, writer)); From 87a9a231f3737c4efc0a30906917cd5a2d2aece9 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Wed, 7 Dec 2022 13:04:52 -0500 Subject: [PATCH 07/12] - adds external doc support for Go Signed-off-by: Vincent Biret --- .../Writers/Go/CodeMethodWriter.cs | 7 +++++- .../Writers/Go/CodeMethodWriterTests.cs | 23 +++++++++++++++++++ 2 files changed, 29 insertions(+), 1 deletion(-) diff --git a/src/Kiota.Builder/Writers/Go/CodeMethodWriter.cs b/src/Kiota.Builder/Writers/Go/CodeMethodWriter.cs index 00f6fbe4de..688f1bc2c6 100644 --- a/src/Kiota.Builder/Writers/Go/CodeMethodWriter.cs +++ b/src/Kiota.Builder/Writers/Go/CodeMethodWriter.cs @@ -230,8 +230,13 @@ private void WriteFactoryMethodBodyForUnionModelForUnDiscriminatedTypes(CodeClas } private void WriteMethodDocumentation(CodeMethod code, string methodName, LanguageWriter writer) { - if(!string.IsNullOrEmpty(code.Documentation.Description)) + if(code.Documentation.DescriptionAvailable) conventions.WriteShortDescription($"{methodName.ToFirstCharacterUpperCase()} {code.Documentation.Description.ToFirstCharacterLowerCase()}", writer); + if(code.Documentation.ExternalDocumentationAvailable) { + conventions.WriteShortDescription($"[{code.Documentation.DocumentationLabel}]", writer); + conventions.WriteShortDescription(string.Empty, writer); + conventions.WriteShortDescription($"[{code.Documentation.DocumentationLabel}]: {code.Documentation.DocumentationLink}", writer); + } } private const string TempParamsVarName = "urlParams"; private static void WriteRawUrlConstructorBody(CodeClass parentClass, CodeMethod codeElement, LanguageWriter writer) diff --git a/tests/Kiota.Builder.Tests/Writers/Go/CodeMethodWriterTests.cs b/tests/Kiota.Builder.Tests/Writers/Go/CodeMethodWriterTests.cs index 750e3219f8..29fcf70f87 100644 --- a/tests/Kiota.Builder.Tests/Writers/Go/CodeMethodWriterTests.cs +++ b/tests/Kiota.Builder.Tests/Writers/Go/CodeMethodWriterTests.cs @@ -1160,6 +1160,29 @@ public void WritesMethodSyncDescription() { AssertExtensions.CurlyBracesAreClosed(result); } [Fact] + public void WritesMethodDescriptionLink() { + method.Documentation.Description = MethodDescription; + method.Documentation.DocumentationLabel = "see more"; + method.Documentation.DocumentationLink = new("https://foo.org/docs"); + method.IsAsync = false; + var parameter = new CodeParameter + { + Documentation = new() { + Description = ParamDescription, + }, + Name = ParamName, + Type = new CodeType + { + Name = "string" + } + }; + method.AddParameter(parameter); + writer.Write(method); + var result = tw.ToString(); + Assert.Contains("[see more]: ", result); + AssertExtensions.CurlyBracesAreClosed(result); + } + [Fact] public void Defensive() { var codeMethodWriter = new CodeMethodWriter(new GoConventionService()); Assert.Throws(() => codeMethodWriter.WriteCodeElement(null, writer)); From ba5e1376cc0b081310fc9ebf7b291924c97fbbf9 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Wed, 7 Dec 2022 13:13:21 -0500 Subject: [PATCH 08/12] - adds a changelog entry for the external docs support Signed-off-by: Vincent Biret --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8732be6ac6..c9db8e0edc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added - Adds description validation rules to help users get the best client experience. [#2019](https://github.com/microsoft/kiota/issues/2019) +- Adds support for external documentation links on request execution methods. [#2036](https://github.com/microsoft/kiota/issues/2036) ### Changed From 53d7098424da41e6be143442c00561e37b341080 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Wed, 7 Dec 2022 13:30:24 -0500 Subject: [PATCH 09/12] - adds class and interface link support for go Signed-off-by: Vincent Biret --- src/Kiota.Builder/KiotaBuilder.cs | 2 ++ .../Writers/Go/CodeClassDeclarationWriter.cs | 1 + .../Writers/Go/CodeInterfaceDeclarationWriter.cs | 1 + src/Kiota.Builder/Writers/Go/CodeMethodWriter.cs | 6 +----- src/Kiota.Builder/Writers/Go/GoConventionService.cs | 8 ++++++++ 5 files changed, 13 insertions(+), 5 deletions(-) diff --git a/src/Kiota.Builder/KiotaBuilder.cs b/src/Kiota.Builder/KiotaBuilder.cs index 32830f0190..90855d9ed7 100644 --- a/src/Kiota.Builder/KiotaBuilder.cs +++ b/src/Kiota.Builder/KiotaBuilder.cs @@ -1234,6 +1234,8 @@ private CodeClass AddModelClass(OpenApiUrlTreeNode currentNode, OpenApiSchema sc Name = declarationName, Kind = CodeClassKind.Model, Documentation = new() { + DocumentationLabel = schema.ExternalDocs?.Description, + DocumentationLink = schema.ExternalDocs?.Url, Description = schema.Description.CleanupDescription() ?? (string.IsNullOrEmpty(schema.Reference?.Id) ? currentNode.GetPathItemDescription(Constants.DefaultOpenApiLabel) : null),// if it's a referenced component, we shouldn't use the path item description as it makes it indeterministic diff --git a/src/Kiota.Builder/Writers/Go/CodeClassDeclarationWriter.cs b/src/Kiota.Builder/Writers/Go/CodeClassDeclarationWriter.cs index 9eb5b5476a..fb3f67c759 100644 --- a/src/Kiota.Builder/Writers/Go/CodeClassDeclarationWriter.cs +++ b/src/Kiota.Builder/Writers/Go/CodeClassDeclarationWriter.cs @@ -11,6 +11,7 @@ protected override void WriteTypeDeclaration(ClassDeclaration codeElement, Langu var className = codeElement.Name.ToFirstCharacterUpperCase(); var currentClass = codeElement.Parent as CodeClass; conventions.WriteShortDescription($"{className} {currentClass.Documentation.Description.ToFirstCharacterLowerCase()}", writer); + conventions.WriteLinkDescription(currentClass.Documentation, writer); writer.StartBlock($"type {className} struct {{"); if(codeElement.Inherits?.AllTypes?.Any() ?? false) { var parentTypeName = conventions.GetTypeString(codeElement.Inherits.AllTypes.First(), currentClass, true, false); diff --git a/src/Kiota.Builder/Writers/Go/CodeInterfaceDeclarationWriter.cs b/src/Kiota.Builder/Writers/Go/CodeInterfaceDeclarationWriter.cs index bcd07f8028..d9d9844a56 100644 --- a/src/Kiota.Builder/Writers/Go/CodeInterfaceDeclarationWriter.cs +++ b/src/Kiota.Builder/Writers/Go/CodeInterfaceDeclarationWriter.cs @@ -11,6 +11,7 @@ protected override void WriteTypeDeclaration(InterfaceDeclaration codeElement, L var inter = codeElement.Parent as CodeInterface; var interName = codeElement.Name.ToFirstCharacterUpperCase(); conventions.WriteShortDescription($"{interName} {inter.Documentation.Description.ToFirstCharacterLowerCase()}", writer); + conventions.WriteLinkDescription(inter.Documentation, writer); writer.WriteLine($"type {interName} interface {{"); writer.IncreaseIndent(); foreach (var implement in codeElement.Implements) { diff --git a/src/Kiota.Builder/Writers/Go/CodeMethodWriter.cs b/src/Kiota.Builder/Writers/Go/CodeMethodWriter.cs index 688f1bc2c6..776c920bcf 100644 --- a/src/Kiota.Builder/Writers/Go/CodeMethodWriter.cs +++ b/src/Kiota.Builder/Writers/Go/CodeMethodWriter.cs @@ -232,11 +232,7 @@ private void WriteFactoryMethodBodyForUnionModelForUnDiscriminatedTypes(CodeClas private void WriteMethodDocumentation(CodeMethod code, string methodName, LanguageWriter writer) { if(code.Documentation.DescriptionAvailable) conventions.WriteShortDescription($"{methodName.ToFirstCharacterUpperCase()} {code.Documentation.Description.ToFirstCharacterLowerCase()}", writer); - if(code.Documentation.ExternalDocumentationAvailable) { - conventions.WriteShortDescription($"[{code.Documentation.DocumentationLabel}]", writer); - conventions.WriteShortDescription(string.Empty, writer); - conventions.WriteShortDescription($"[{code.Documentation.DocumentationLabel}]: {code.Documentation.DocumentationLink}", writer); - } + conventions.WriteLinkDescription(code.Documentation, writer); } private const string TempParamsVarName = "urlParams"; private static void WriteRawUrlConstructorBody(CodeClass parentClass, CodeMethod codeElement, LanguageWriter writer) diff --git a/src/Kiota.Builder/Writers/Go/GoConventionService.cs b/src/Kiota.Builder/Writers/Go/GoConventionService.cs index d2b3959588..7a870ceb45 100644 --- a/src/Kiota.Builder/Writers/Go/GoConventionService.cs +++ b/src/Kiota.Builder/Writers/Go/GoConventionService.cs @@ -144,6 +144,14 @@ public override void WriteShortDescription(string description, LanguageWriter wr { writer.WriteLine($"{DocCommentPrefix}{description}"); } + public void WriteLinkDescription(CodeDocumentation documentation, LanguageWriter writer) + { + if(documentation.ExternalDocumentationAvailable) { + WriteShortDescription($"[{documentation.DocumentationLabel}]", writer); + WriteShortDescription(string.Empty, writer); + WriteShortDescription($"[{documentation.DocumentationLabel}]: {documentation.DocumentationLink}", writer); + } + } #pragma warning disable CA1822 // Method should be static internal void AddRequestBuilderBody(CodeClass parentClass, string returnType, LanguageWriter writer, string urlTemplateVarName = default, IEnumerable pathParameters = default) { From bec875b646c5b7f71c129bacdbef7c363f5d4691 Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Wed, 7 Dec 2022 13:39:31 -0500 Subject: [PATCH 10/12] - adds link documentation support to csharp classes Signed-off-by: Vincent Biret --- .../Writers/CSharp/CSharpConventionService.cs | 10 ++++++++++ .../CSharp/CodeClassDeclarationWriter.cs | 8 ++++---- .../Writers/CSharp/CodeMethodWriter.cs | 17 +++++------------ 3 files changed, 19 insertions(+), 16 deletions(-) diff --git a/src/Kiota.Builder/Writers/CSharp/CSharpConventionService.cs b/src/Kiota.Builder/Writers/CSharp/CSharpConventionService.cs index 097dc441e3..93a059c7a2 100644 --- a/src/Kiota.Builder/Writers/CSharp/CSharpConventionService.cs +++ b/src/Kiota.Builder/Writers/CSharp/CSharpConventionService.cs @@ -20,6 +20,16 @@ public override void WriteShortDescription(string description, LanguageWriter wr if(!string.IsNullOrEmpty(description)) writer.WriteLine($"{DocCommentPrefix}{description.CleanupXMLString()}"); } + public void WriteLongDescription(CodeDocumentation documentation, LanguageWriter writer) { + if(documentation.DescriptionAvailable || documentation.ExternalDocumentationAvailable) { + writer.WriteLine($"{DocCommentPrefix}"); + if (documentation.DescriptionAvailable) + writer.WriteLine($"{DocCommentPrefix}{documentation.Description.CleanupXMLString()}"); + if(documentation.ExternalDocumentationAvailable) + writer.WriteLine($"{DocCommentPrefix}{documentation.DocumentationLabel} "); + writer.WriteLine($"{DocCommentPrefix}"); + } + } public override string GetAccessModifier(AccessModifier access) { return access switch { diff --git a/src/Kiota.Builder/Writers/CSharp/CodeClassDeclarationWriter.cs b/src/Kiota.Builder/Writers/CSharp/CodeClassDeclarationWriter.cs index 4c49891909..81f7a6744c 100644 --- a/src/Kiota.Builder/Writers/CSharp/CodeClassDeclarationWriter.cs +++ b/src/Kiota.Builder/Writers/CSharp/CodeClassDeclarationWriter.cs @@ -27,11 +27,11 @@ public override void WriteCodeElement(ClassDeclaration codeElement, LanguageWrit } var derivedTypes = new List{codeElement.Inherits?.Name} - .Union(codeElement.Implements.Select(x => x.Name)) - .Where(x => x != null); - var derivation = derivedTypes.Any() ? ": " + derivedTypes.Select(x => x.ToFirstCharacterUpperCase()).Aggregate((x, y) => $"{x}, {y}") + " " : string.Empty; + .Union(codeElement.Implements.Select(static x => x.Name)) + .Where(static x => x != null); + var derivation = derivedTypes.Any() ? ": " + derivedTypes.Select(static x => x.ToFirstCharacterUpperCase()).Aggregate(static (x, y) => $"{x}, {y}") + " " : string.Empty; if(codeElement.Parent is CodeClass parentClass) - conventions.WriteShortDescription(parentClass.Documentation.Description, writer); + conventions.WriteLongDescription(parentClass.Documentation, writer); writer.WriteLine($"public class {codeElement.Name.ToFirstCharacterUpperCase()} {derivation}{{"); writer.IncreaseIndent(); } diff --git a/src/Kiota.Builder/Writers/CSharp/CodeMethodWriter.cs b/src/Kiota.Builder/Writers/CSharp/CodeMethodWriter.cs index 5e0a8d5044..ce141f5b4a 100644 --- a/src/Kiota.Builder/Writers/CSharp/CodeMethodWriter.cs +++ b/src/Kiota.Builder/Writers/CSharp/CodeMethodWriter.cs @@ -525,18 +525,11 @@ protected string GetSendRequestMethodName(bool isVoid, CodeElement currentElemen } private void WriteMethodDocumentation(CodeMethod code, LanguageWriter writer) { - var parametersWithDescription = code.Parameters.Where(static x => x.Documentation.DescriptionAvailable); - if (code.Documentation.DescriptionAvailable || parametersWithDescription.Any()) - { - writer.WriteLine($"{conventions.DocCommentPrefix}"); - if (code.Documentation.DescriptionAvailable) - writer.WriteLine($"{conventions.DocCommentPrefix}{code.Documentation.Description.CleanupXMLString()}"); - if(code.Documentation.ExternalDocumentationAvailable) - writer.WriteLine($"{conventions.DocCommentPrefix}{code.Documentation.DocumentationLabel} "); - writer.WriteLine($"{conventions.DocCommentPrefix}"); - foreach (var paramWithDescription in parametersWithDescription.OrderBy(static x => x.Name, StringComparer.OrdinalIgnoreCase)) - writer.WriteLine($"{conventions.DocCommentPrefix}{paramWithDescription.Documentation.Description.CleanupXMLString()}"); - } + conventions.WriteLongDescription(code.Documentation, 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()}"); } private static readonly BaseCodeParameterOrderComparer parameterOrderComparer = new(); private void WriteMethodPrototype(CodeMethod code, LanguageWriter writer, string returnType, bool inherits, bool isVoid) From 2d2d9afb3cab3a6650e33a6bd276e54906fd300f Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Wed, 7 Dec 2022 13:52:25 -0500 Subject: [PATCH 11/12] - adds support for external documentation in java Signed-off-by: Vincent Biret --- .../Writers/CSharp/CSharpConventionService.cs | 1 + .../Writers/Go/GoConventionService.cs | 1 + .../Java/CodeClassDeclarationWriter.cs | 2 +- .../Writers/Java/CodeMethodWriter.cs | 29 ++++++++----------- .../Writers/Java/JavaConventionService.cs | 14 +++++++++ 5 files changed, 29 insertions(+), 18 deletions(-) diff --git a/src/Kiota.Builder/Writers/CSharp/CSharpConventionService.cs b/src/Kiota.Builder/Writers/CSharp/CSharpConventionService.cs index 93a059c7a2..5d3a134fd7 100644 --- a/src/Kiota.Builder/Writers/CSharp/CSharpConventionService.cs +++ b/src/Kiota.Builder/Writers/CSharp/CSharpConventionService.cs @@ -21,6 +21,7 @@ public override void WriteShortDescription(string description, LanguageWriter wr writer.WriteLine($"{DocCommentPrefix}{description.CleanupXMLString()}"); } public void WriteLongDescription(CodeDocumentation documentation, LanguageWriter writer) { + if(documentation is null) return; if(documentation.DescriptionAvailable || documentation.ExternalDocumentationAvailable) { writer.WriteLine($"{DocCommentPrefix}"); if (documentation.DescriptionAvailable) diff --git a/src/Kiota.Builder/Writers/Go/GoConventionService.cs b/src/Kiota.Builder/Writers/Go/GoConventionService.cs index 7a870ceb45..1dd6ca09e0 100644 --- a/src/Kiota.Builder/Writers/Go/GoConventionService.cs +++ b/src/Kiota.Builder/Writers/Go/GoConventionService.cs @@ -146,6 +146,7 @@ public override void WriteShortDescription(string description, LanguageWriter wr } public void WriteLinkDescription(CodeDocumentation documentation, LanguageWriter writer) { + if(documentation is null) return; if(documentation.ExternalDocumentationAvailable) { WriteShortDescription($"[{documentation.DocumentationLabel}]", writer); WriteShortDescription(string.Empty, writer); diff --git a/src/Kiota.Builder/Writers/Java/CodeClassDeclarationWriter.cs b/src/Kiota.Builder/Writers/Java/CodeClassDeclarationWriter.cs index 5d4e2c4a1f..6ee7e21c57 100644 --- a/src/Kiota.Builder/Writers/Java/CodeClassDeclarationWriter.cs +++ b/src/Kiota.Builder/Writers/Java/CodeClassDeclarationWriter.cs @@ -29,7 +29,7 @@ public override void WriteCodeElement(ClassDeclaration codeElement, LanguageWrit } 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)}"); - conventions.WriteShortDescription((codeElement.Parent as CodeClass)?.Documentation.Description, writer); + conventions.WriteLongDescription((codeElement.Parent as CodeClass)?.Documentation, writer); var innerClassStatic = codeElement.Parent is CodeClass currentClass && currentClass.IsOfKind(CodeClassKind.Model) && currentClass.Parent is CodeClass ? "static " : string.Empty; //https://stackoverflow.com/questions/47541459/no-enclosing-instance-is-accessible-must-qualify-the-allocation-with-an-enclosi writer.WriteLine($"public {innerClassStatic}class {codeElement.Name.ToFirstCharacterUpperCase()}{derivation} {{"); writer.IncreaseIndent(); diff --git a/src/Kiota.Builder/Writers/Java/CodeMethodWriter.cs b/src/Kiota.Builder/Writers/Java/CodeMethodWriter.cs index df10ae9a30..7c316b2ca8 100644 --- a/src/Kiota.Builder/Writers/Java/CodeMethodWriter.cs +++ b/src/Kiota.Builder/Writers/Java/CodeMethodWriter.cs @@ -633,23 +633,18 @@ private string WriteMethodPrototype(CodeMethod code, LanguageWriter writer, stri return collectionCorrectedReturnType; } private void WriteMethodDocumentation(CodeMethod code, LanguageWriter writer) { - var parametersWithDescription = code.Parameters.Where(static x => x.Documentation.DescriptionAvailable); - if (code.Documentation.DescriptionAvailable || parametersWithDescription.Any()) { - writer.WriteLine(conventions.DocCommentStart); - if(code.Documentation.DescriptionAvailable) - writer.WriteLine($"{conventions.DocCommentPrefix}{JavaConventionService.RemoveInvalidDescriptionCharacters(code.Documentation.Description)}"); - foreach(var paramWithDescription in parametersWithDescription.OrderBy(x => x.Name)) - writer.WriteLine($"{conventions.DocCommentPrefix}@param {paramWithDescription.Name} {JavaConventionService.RemoveInvalidDescriptionCharacters(paramWithDescription.Documentation.Description)}"); - - if(code.IsAsync) - writer.WriteLine($"{conventions.DocCommentPrefix}@return a CompletableFuture of {code.ReturnType.Name}"); - else - writer.WriteLine($"{conventions.DocCommentPrefix}@return a {code.ReturnType.Name}"); - - if(code.Documentation.ExternalDocumentationAvailable) - writer.WriteLine($"{conventions.DocCommentPrefix}@see {code.Documentation.DocumentationLabel}"); - writer.WriteLine(conventions.DocCommentEnd); - } + var returnRemark = code.IsAsync switch { + true => $"@return a CompletableFuture of {code.ReturnType.Name}", + false => $"@return a {code.ReturnType.Name}", + }; + conventions.WriteLongDescription(code.Documentation, + 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 })); + } private string GetDeserializationMethodName(CodeTypeBase propType, CodeMethod method) { var isCollection = propType.CollectionKind != CodeTypeBase.CodeTypeCollectionKind.None; diff --git a/src/Kiota.Builder/Writers/Java/JavaConventionService.cs b/src/Kiota.Builder/Writers/Java/JavaConventionService.cs index 11732585ee..d6555d9f76 100644 --- a/src/Kiota.Builder/Writers/Java/JavaConventionService.cs +++ b/src/Kiota.Builder/Writers/Java/JavaConventionService.cs @@ -85,6 +85,20 @@ public override void WriteShortDescription(string description, LanguageWriter wr if(!string.IsNullOrEmpty(description)) writer.WriteLine($"{DocCommentStart} {RemoveInvalidDescriptionCharacters(description)}{DocCommentEnd}"); } + public void WriteLongDescription(CodeDocumentation documentation, LanguageWriter writer, IEnumerable additionalRemarks = default) { + if(documentation is null) return; + if (documentation.DescriptionAvailable || documentation.ExternalDocumentationAvailable || additionalRemarks.Any()) { + writer.WriteLine(DocCommentStart); + if(documentation.DescriptionAvailable) + writer.WriteLine($"{DocCommentPrefix}{RemoveInvalidDescriptionCharacters(documentation.Description)}"); + foreach(var additionalRemark in additionalRemarks) + writer.WriteLine($"{DocCommentPrefix}{additionalRemark}"); + + if(documentation.ExternalDocumentationAvailable) + writer.WriteLine($"{DocCommentPrefix}@see {documentation.DocumentationLabel}"); + writer.WriteLine(DocCommentEnd); + } + } private static readonly Regex nonAsciiReplaceRegex = new (@"[^\u0000-\u007F]+", RegexOptions.Compiled); internal static string RemoveInvalidDescriptionCharacters(string originalDescription) => string.IsNullOrEmpty(originalDescription) ? From 95a7bcae3f3805510a6e1da2c848b05394a61b4c Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Wed, 7 Dec 2022 14:08:52 -0500 Subject: [PATCH 12/12] - adds link reference support for typescript classes Signed-off-by: Vincent Biret --- .../Java/CodeClassDeclarationWriter.cs | 3 +- .../Writers/Java/JavaConventionService.cs | 4 ++- .../TypeScript/CodeClassDeclarationWriter.cs | 3 +- .../Writers/TypeScript/CodeMethodWriter.cs | 29 ++++++++----------- .../TypeScript/TypeScriptConventionService.cs | 17 +++++++++++ 5 files changed, 36 insertions(+), 20 deletions(-) diff --git a/src/Kiota.Builder/Writers/Java/CodeClassDeclarationWriter.cs b/src/Kiota.Builder/Writers/Java/CodeClassDeclarationWriter.cs index 6ee7e21c57..1789d8ad77 100644 --- a/src/Kiota.Builder/Writers/Java/CodeClassDeclarationWriter.cs +++ b/src/Kiota.Builder/Writers/Java/CodeClassDeclarationWriter.cs @@ -29,7 +29,8 @@ public override void WriteCodeElement(ClassDeclaration codeElement, LanguageWrit } 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)}"); - conventions.WriteLongDescription((codeElement.Parent as CodeClass)?.Documentation, writer); + if (codeElement.Parent is CodeClass parentClass) + conventions.WriteLongDescription(parentClass.Documentation, writer); var innerClassStatic = codeElement.Parent is CodeClass currentClass && currentClass.IsOfKind(CodeClassKind.Model) && currentClass.Parent is CodeClass ? "static " : string.Empty; //https://stackoverflow.com/questions/47541459/no-enclosing-instance-is-accessible-must-qualify-the-allocation-with-an-enclosi writer.WriteLine($"public {innerClassStatic}class {codeElement.Name.ToFirstCharacterUpperCase()}{derivation} {{"); writer.IncreaseIndent(); diff --git a/src/Kiota.Builder/Writers/Java/JavaConventionService.cs b/src/Kiota.Builder/Writers/Java/JavaConventionService.cs index d6555d9f76..71da7a9a03 100644 --- a/src/Kiota.Builder/Writers/Java/JavaConventionService.cs +++ b/src/Kiota.Builder/Writers/Java/JavaConventionService.cs @@ -87,11 +87,13 @@ public override void WriteShortDescription(string description, LanguageWriter wr } public void WriteLongDescription(CodeDocumentation documentation, LanguageWriter writer, IEnumerable additionalRemarks = default) { if(documentation is null) return; + if(additionalRemarks == default) + additionalRemarks = Enumerable.Empty(); if (documentation.DescriptionAvailable || documentation.ExternalDocumentationAvailable || additionalRemarks.Any()) { writer.WriteLine(DocCommentStart); if(documentation.DescriptionAvailable) writer.WriteLine($"{DocCommentPrefix}{RemoveInvalidDescriptionCharacters(documentation.Description)}"); - foreach(var additionalRemark in additionalRemarks) + foreach(var additionalRemark in additionalRemarks.Where(static x => !string.IsNullOrEmpty(x))) writer.WriteLine($"{DocCommentPrefix}{additionalRemark}"); if(documentation.ExternalDocumentationAvailable) diff --git a/src/Kiota.Builder/Writers/TypeScript/CodeClassDeclarationWriter.cs b/src/Kiota.Builder/Writers/TypeScript/CodeClassDeclarationWriter.cs index 7a669270dc..4066e4aa2a 100644 --- a/src/Kiota.Builder/Writers/TypeScript/CodeClassDeclarationWriter.cs +++ b/src/Kiota.Builder/Writers/TypeScript/CodeClassDeclarationWriter.cs @@ -21,7 +21,8 @@ public override void WriteCodeElement(ClassDeclaration codeElement, LanguageWrit var inheritSymbol = conventions.GetTypeString(codeElement.Inherits, codeElement); var derivation = (inheritSymbol == null ? string.Empty : $" extends {inheritSymbol}") + (!codeElement.Implements.Any() ? string.Empty : $" implements {codeElement.Implements.Select(x => x.Name).Aggregate((x,y) => x + ", " + y)}"); - conventions.WriteShortDescription((codeElement.Parent as CodeClass).Documentation.Description, writer); + if(codeElement.Parent is CodeClass parentClass ) + conventions.WriteLongDescription(parentClass.Documentation, writer); writer.WriteLine($"export class {codeElement.Name.ToFirstCharacterUpperCase()}{derivation} {{"); writer.IncreaseIndent(); } diff --git a/src/Kiota.Builder/Writers/TypeScript/CodeMethodWriter.cs b/src/Kiota.Builder/Writers/TypeScript/CodeMethodWriter.cs index 1e84747896..0bce64ed7a 100644 --- a/src/Kiota.Builder/Writers/TypeScript/CodeMethodWriter.cs +++ b/src/Kiota.Builder/Writers/TypeScript/CodeMethodWriter.cs @@ -342,23 +342,18 @@ private void WriteSerializerBody(bool inherits, CodeClass parentClass, LanguageW writer.WriteLine($"writer.writeAdditionalData(this.{additionalDataProperty.Name.ToFirstCharacterLowerCase()});"); } private void WriteMethodDocumentation(CodeMethod code, LanguageWriter writer, bool isVoid) { - var parametersWithDescription = code.Parameters.Where(static x => x.Documentation.DescriptionAvailable); - if (code.Documentation.DescriptionAvailable || parametersWithDescription.Any()) { - writer.WriteLine(localConventions.DocCommentStart); - if(code.Documentation.DescriptionAvailable) - writer.WriteLine($"{localConventions.DocCommentPrefix}{TypeScriptConventionService.RemoveInvalidDescriptionCharacters(code.Documentation.Description)}"); - foreach(var paramWithDescription in parametersWithDescription.OrderBy(x => x.Name)) - writer.WriteLine($"{localConventions.DocCommentPrefix}@param {paramWithDescription.Name} {TypeScriptConventionService.RemoveInvalidDescriptionCharacters(paramWithDescription.Documentation.Description)}"); - - if(!isVoid) - if(code.IsAsync) - writer.WriteLine($"{localConventions.DocCommentPrefix}@returns a Promise of {code.ReturnType.Name.ToFirstCharacterUpperCase()}"); - else - writer.WriteLine($"{localConventions.DocCommentPrefix}@returns a {code.ReturnType.Name}"); - if(code.Documentation.ExternalDocumentationAvailable) - writer.WriteLine($"{localConventions.DocCommentPrefix}@see {{@link {code.Documentation.DocumentationLink}|{code.Documentation.DocumentationLabel}}}"); - writer.WriteLine(localConventions.DocCommentEnd); - } + 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}", + }; + localConventions.WriteLongDescription(code.Documentation, + 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 })); } 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 45003d5084..db3d942c39 100644 --- a/src/Kiota.Builder/Writers/TypeScript/TypeScriptConventionService.cs +++ b/src/Kiota.Builder/Writers/TypeScript/TypeScriptConventionService.cs @@ -125,4 +125,21 @@ public override void WriteShortDescription(string description, LanguageWriter wr if(!string.IsNullOrEmpty(description)) writer.WriteLine($"{DocCommentStart} {RemoveInvalidDescriptionCharacters(description)}{DocCommentEnd}"); } + public void WriteLongDescription(CodeDocumentation documentation, LanguageWriter writer, IEnumerable additionalRemarks = default) { + if(documentation is null) return; + if(additionalRemarks == default) + additionalRemarks = Enumerable.Empty(); + if (documentation.DescriptionAvailable || documentation.ExternalDocumentationAvailable || additionalRemarks.Any()) { + writer.WriteLine(DocCommentStart); + if(documentation.DescriptionAvailable) + writer.WriteLine($"{DocCommentPrefix}{RemoveInvalidDescriptionCharacters(documentation.Description)}"); + foreach(var additionalRemark in additionalRemarks.Where(static x => !string.IsNullOrEmpty(x))) + writer.WriteLine($"{DocCommentPrefix}{additionalRemark}"); + + if(documentation.ExternalDocumentationAvailable) + writer.WriteLine($"{DocCommentPrefix}@see {{@link {documentation.DocumentationLink}|{documentation.DocumentationLabel}}}"); + writer.WriteLine(DocCommentEnd); + } + } + }