Merge pull request #4121 from microsoft/feature/exception-doc-comments

feature/exception doc comments

CHANGELOG.md

@@ -14,6 +14,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Keyword in enum names for go should not be escaped. [#2877](https://github.com/microsoft/kiota/issues/2877)
 - Generator method code reduction in Python. [#3695](https://github.com/microsoft/kiota/issues/3695)
 
+- Fixed return doc comments for Go/Java/CSharp/TypeScript.
+- Fixed type names in doc comments and deprecation noticed across languages.
+- Added thrown exceptions in doc comments for Go/CSharp/Java/TypeScript. [#3811](https://github.com/microsoft/kiota/issues/3811)
+
 ## [1.11.1] - 2024-02-05
 
 ### Added

src/Kiota.Builder/CodeDOM/CodeConstant.cs

@@ -35,7 +35,7 @@ public CodeDocumentation Documentation
             Kind = CodeConstantKind.QueryParametersMapper,
             OriginalCodeElement = source,
         };
-        result.Documentation.Description = "Mapper for query parameters from symbol name to serialization name represented as a constant.";
+        result.Documentation.DescriptionTemplate = "Mapper for query parameters from symbol name to serialization name represented as a constant.";
         return result;
     }
     public static CodeConstant? FromCodeEnum(CodeEnum source)
@@ -63,7 +63,7 @@ public CodeDocumentation Documentation
             UriTemplate = urlTemplateProperty.DefaultValue,
             OriginalCodeElement = codeClass
         };
-        result.Documentation.Description = "Uri template for the request builder.";
+        result.Documentation.DescriptionTemplate = "Uri template for the request builder.";
         return result;
     }
     public static CodeConstant? FromRequestBuilderToNavigationMetadata(CodeClass codeClass, CodeUsing[]? usingsToAdd = default)
@@ -79,7 +79,7 @@ public CodeDocumentation Documentation
             Kind = CodeConstantKind.NavigationMetadata,
             OriginalCodeElement = codeClass,
         };
-        result.Documentation.Description = "Metadata for all the navigation properties in the request builder.";
+        result.Documentation.DescriptionTemplate = "Metadata for all the navigation properties in the request builder.";
         if (usingsToAdd is { Length: > 0 } usingsToAddList)
             result.AddUsing(usingsToAddList);
         return result;
@@ -96,7 +96,7 @@ public CodeDocumentation Documentation
             Kind = CodeConstantKind.RequestsMetadata,
             OriginalCodeElement = codeClass,
         };
-        result.Documentation.Description = "Metadata for all the requests in the request builder.";
+        result.Documentation.DescriptionTemplate = "Metadata for all the requests in the request builder.";
         if (usingsToAdd is { Length: > 0 } usingsToAddList)
             result.AddUsing(usingsToAddList);
         return result;

src/Kiota.Builder/CodeDOM/CodeDocumentation.cs

@@ -1,4 +1,7 @@
 using System;
+using System.Collections.Concurrent;
+using System.Collections.Generic;
+using System.Linq;
 
 namespace Kiota.Builder.CodeDOM;
 
@@ -7,10 +10,19 @@ namespace Kiota.Builder.CodeDOM;
 /// </summary>
 public class CodeDocumentation : ICloneable
 {
+    /// <summary>
+    /// Instantiates a new instance of the <see cref="CodeDocumentation"/> class.
+    /// </summary>
+    /// <param name="typeReferences">The references used by the description</param>
+    public CodeDocumentation(Dictionary<string, CodeTypeBase>? typeReferences = null)
+    {
+        if (typeReferences is not null)
+            TypeReferences = new(typeReferences, StringComparer.OrdinalIgnoreCase);
+    }
     /// <summary>
     /// The description of the current element.
     /// </summary>
-    public string Description
+    public string DescriptionTemplate
     {
         get; set;
     } = string.Empty;
@@ -34,14 +46,44 @@ public object Clone()
     {
         return new CodeDocumentation
         {
-            Description = Description,
+            DescriptionTemplate = DescriptionTemplate,
             DocumentationLink = DocumentationLink == null ? null : new(DocumentationLink.ToString()),
             DocumentationLabel = DocumentationLabel,
+            TypeReferences = new(TypeReferences, StringComparer.OrdinalIgnoreCase)
         };
     }
+    /// <summary>
+    /// References to be resolved when the description is emitted.
+    /// Keys MUST match the description template tokens or they will be ignored.
+    /// </summary>
+    public ConcurrentDictionary<string, CodeTypeBase> TypeReferences { get; private set; } = new(StringComparer.OrdinalIgnoreCase);
+    public string GetDescription(Func<CodeTypeBase, string> typeReferenceResolver, string? typeReferencePrefix = null, string? typeReferenceSuffix = null, Func<string, string>? normalizationFunc = null)
+    {
+        return GetDescriptionInternal(DescriptionTemplate, typeReferenceResolver, TypeReferences, typeReferencePrefix, typeReferenceSuffix, normalizationFunc);
+    }
+    internal static string GetDescriptionInternal(string descriptionTemplate, Func<CodeTypeBase, string> typeReferenceResolver, IDictionary<string, CodeTypeBase>? typeReferences = null, string? typeReferencePrefix = null, string? typeReferenceSuffix = null, Func<string, string>? normalizationFunc = null)
+    {
+        ArgumentNullException.ThrowIfNull(typeReferenceResolver);
+        if (string.IsNullOrEmpty(descriptionTemplate))
+            return string.Empty;
+        var description = normalizationFunc is null ? descriptionTemplate : normalizationFunc(descriptionTemplate);
+        if (typeReferences is not null)
+            foreach (var (key, value) in typeReferences)
+            {
+                var resolvedValue = value switch
+                {
+                    CodeComposedTypeBase codeComposedTypeBase => string.Join(", ", codeComposedTypeBase.Types.Select(x => $"{typeReferencePrefix}{typeReferenceResolver(x)}{typeReferenceSuffix}").Order(StringComparer.OrdinalIgnoreCase)) is string s && !string.IsNullOrEmpty(s) ?
+                                                                        s : typeReferenceResolver(value),
+                    _ => $"{typeReferencePrefix}{typeReferenceResolver(value)}{typeReferenceSuffix}",
+                };
+                if (!string.IsNullOrEmpty(resolvedValue))
+                    description = description.Replace($"{{{key}}}", resolvedValue, StringComparison.OrdinalIgnoreCase);
+            }
+        return description;
+    }
     public bool DescriptionAvailable
     {
-        get => !string.IsNullOrEmpty(Description);
+        get => !string.IsNullOrEmpty(DescriptionTemplate);
     }
     public bool ExternalDocumentationAvailable
     {

src/Kiota.Builder/CodeDOM/DeprecationInformation.cs

@@ -1,5 +1,14 @@
 using System;
+using System.Collections.Generic;
 
 namespace Kiota.Builder.CodeDOM;
 
-public record DeprecationInformation(string? Description, DateTimeOffset? Date = null, DateTimeOffset? RemovalDate = null, string? Version = "", bool IsDeprecated = true);
+public record DeprecationInformation(string? DescriptionTemplate, DateTimeOffset? Date = null, DateTimeOffset? RemovalDate = null, string? Version = "", bool IsDeprecated = true, Dictionary<string, CodeTypeBase>? TypeReferences = null)
+{
+    public string GetDescription(Func<CodeTypeBase, string> typeReferenceResolver, string? typeReferencePrefix = null, string? typeReferenceSuffix = null)
+    {
+        if (DescriptionTemplate is null)
+            return string.Empty;
+        return CodeDocumentation.GetDescriptionInternal(DescriptionTemplate, typeReferenceResolver, TypeReferences, typeReferencePrefix, typeReferenceSuffix);
+    }
+};