Merge pull request #4173 from microsoft/andrueastman/fixTags

Fixes unclosed documentation tags in dotnet
microsoft · Feb 13, 2024 · 82e5a40 · 82e5a40
2 parents c96a23e + 124a375
commit 82e5a40
Show file tree

Hide file tree

Showing 4 changed files with 13 additions and 4 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -20,6 +20,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 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)
+- Fixed `cref` tags not closed in doc comments in CSharp generation.
 - Deduplicates 4XX and 5XX error mappings when they map to the same type to reduce emitted code. [#4025](https://github.com/microsoft/kiota/issues/4025)
 - 📢📢📢 Java generation is now stable! 🚀🚀🚀 special thanks to @andreaTP (Red Hat) for all the help.
 

diff --git a/src/Kiota.Builder/Writers/CSharp/CSharpConventionService.cs b/src/Kiota.Builder/Writers/CSharp/CSharpConventionService.cs
@@ -44,7 +44,7 @@ public override void WriteShortDescription(IDocumentedElement element, LanguageW
         ArgumentNullException.ThrowIfNull(element);
         if (element is not CodeElement codeElement) return;
         if (!element.Documentation.DescriptionAvailable) return;
-        var description = element.Documentation.GetDescription(type => GetTypeString(type, codeElement), ReferenceTypePrefix, ReferenceTypeSuffix, static x => x.CleanupXMLString());
+        var description = element.Documentation.GetDescription(type => GetTypeStringForDocumentation(type, codeElement), normalizationFunc: static x => x.CleanupXMLString());
         writer.WriteLine($"{DocCommentPrefix}{prefix}{description}{suffix}");
     }
     public void WriteAdditionalDescriptionItem(string description, LanguageWriter writer)
@@ -64,7 +64,7 @@ public void WriteLongDescription(IDocumentedElement element, LanguageWriter writ
             writer.WriteLine($"{DocCommentPrefix}<summary>");
             if (documentation.DescriptionAvailable)
             {
-                var description = element.Documentation.GetDescription(type => GetTypeString(type, codeElement), ReferenceTypePrefix, ReferenceTypeSuffix, static x => x.CleanupXMLString());
+                var description = element.Documentation.GetDescription(type => GetTypeStringForDocumentation(type, codeElement), normalizationFunc: static x => x.CleanupXMLString());
                 writer.WriteLine($"{DocCommentPrefix}{description}");
             }
             if (documentation.ExternalDocumentationAvailable)
@@ -151,6 +151,14 @@ private static IEnumerable<CodeNamespace> GetAllNamespaces(CodeNamespace ns)
                 yield return childNsSegment;
         }
     }
+    public string GetTypeStringForDocumentation(CodeTypeBase code, CodeElement targetElement)
+    {
+        var typeString = GetTypeString(code, targetElement, true, false);// dont include nullable markers
+        if (typeString.EndsWith('>'))
+            return typeString.CleanupXMLString(); // don't generate cref links for generic types as concrete types generate invalid links
+
+        return $"{ReferenceTypePrefix}{typeString.CleanupXMLString()}{ReferenceTypeSuffix}";
+    }
     public override string GetTypeString(CodeTypeBase code, CodeElement targetElement, bool includeCollectionInformation = true, LanguageWriter? writer = null)
     {
         return GetTypeString(code, targetElement, includeCollectionInformation, true);

diff --git a/src/Kiota.Builder/Writers/CSharp/CodeIndexerWriter.cs b/src/Kiota.Builder/Writers/CSharp/CodeIndexerWriter.cs
@@ -14,7 +14,7 @@ public override void WriteCodeElement(CodeIndexer codeElement, LanguageWriter wr
         var returnType = conventions.GetTypeString(codeElement.ReturnType, codeElement);
         conventions.WriteShortDescription(codeElement, writer);//TODO make the parameter name dynamic in v2
         conventions.WriteShortDescription(codeElement.IndexParameter, writer, $"<param name=\"position\">", "</param>");
-        conventions.WriteAdditionalDescriptionItem($"<returns>A <cref=\"{conventions.GetTypeString(codeElement.ReturnType, codeElement)}\"></returns>", writer);
+        conventions.WriteAdditionalDescriptionItem($"<returns>A {conventions.GetTypeStringForDocumentation(codeElement.ReturnType, codeElement)}</returns>", writer);
         conventions.WriteDeprecationAttribute(codeElement, writer);
         writer.StartBlock($"public {returnType} this[{conventions.GetTypeString(codeElement.IndexParameter.Type, codeElement)} position] {{ get {{");
         if (parentClass.GetPropertyOfKind(CodePropertyKind.PathParameters) is CodeProperty pathParametersProp)

diff --git a/src/Kiota.Builder/Writers/CSharp/CodeMethodWriter.cs b/src/Kiota.Builder/Writers/CSharp/CodeMethodWriter.cs
@@ -544,7 +544,7 @@ private void WriteMethodDocumentation(CodeMethod code, LanguageWriter writer)
     {
         conventions.WriteLongDescription(code, writer);
         if (!"void".Equals(code.ReturnType.Name, StringComparison.OrdinalIgnoreCase) && code.Kind is not CodeMethodKind.ClientConstructor or CodeMethodKind.Constructor)
-            conventions.WriteAdditionalDescriptionItem($"<returns>A <cref=\"{conventions.GetTypeString(code.ReturnType, code)}\"></returns>", writer);
+            conventions.WriteAdditionalDescriptionItem($"<returns>A {conventions.GetTypeStringForDocumentation(code.ReturnType, code)}</returns>", writer);
         foreach (var paramWithDescription in code.Parameters
                                                 .Where(static x => x.Documentation.DescriptionAvailable)
                                                 .OrderBy(static x => x.Name, StringComparer.OrdinalIgnoreCase))