From df7fdd984f26bb6c219ee1309e90b6b65c8265f0 Mon Sep 17 00:00:00 2001 From: Andrew Omondi Date: Tue, 13 Feb 2024 15:30:47 +0300 Subject: [PATCH 1/2] Fixing cref tags --- CHANGELOG.md | 1 + src/Kiota.Builder/Writers/CSharp/CodeIndexerWriter.cs | 2 +- src/Kiota.Builder/Writers/CSharp/CodeMethodWriter.cs | 2 +- 3 files changed, 3 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index db2097415b..40f04bb798 100644 --- 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/CodeIndexerWriter.cs b/src/Kiota.Builder/Writers/CSharp/CodeIndexerWriter.cs index cde95bac5b..a218bfdd09 100644 --- 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, $"", ""); - conventions.WriteAdditionalDescriptionItem($"A ", writer); + conventions.WriteAdditionalDescriptionItem($"A ", writer); conventions.WriteDeprecationAttribute(codeElement, writer); writer.StartBlock($"public {returnType} this[{conventions.GetTypeString(codeElement.IndexParameter.Type, codeElement)} position] {{ get {{"); if (parentClass.GetPropertyOfKind(CodePropertyKind.PathParameters) is CodeProperty pathParametersProp) diff --git a/src/Kiota.Builder/Writers/CSharp/CodeMethodWriter.cs b/src/Kiota.Builder/Writers/CSharp/CodeMethodWriter.cs index a856dd6a63..289aca65d5 100644 --- 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($"A ", writer); + conventions.WriteAdditionalDescriptionItem($"A ", writer); foreach (var paramWithDescription in code.Parameters .Where(static x => x.Documentation.DescriptionAvailable) .OrderBy(static x => x.Name, StringComparer.OrdinalIgnoreCase)) From 124a375673424757d86d03619f099778be0c6334 Mon Sep 17 00:00:00 2001 From: Andrew Omondi Date: Tue, 13 Feb 2024 17:38:00 +0300 Subject: [PATCH 2/2] Cleanup --- .../Writers/CSharp/CSharpConventionService.cs | 12 ++++++++++-- .../Writers/CSharp/CodeIndexerWriter.cs | 2 +- src/Kiota.Builder/Writers/CSharp/CodeMethodWriter.cs | 2 +- 3 files changed, 12 insertions(+), 4 deletions(-) diff --git a/src/Kiota.Builder/Writers/CSharp/CSharpConventionService.cs b/src/Kiota.Builder/Writers/CSharp/CSharpConventionService.cs index 9a965ca619..dbbb3bdff5 100644 --- 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}"); 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 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 index a218bfdd09..89b3b292d6 100644 --- 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, $"", ""); - conventions.WriteAdditionalDescriptionItem($"A ", writer); + conventions.WriteAdditionalDescriptionItem($"A {conventions.GetTypeStringForDocumentation(codeElement.ReturnType, codeElement)}", writer); conventions.WriteDeprecationAttribute(codeElement, writer); writer.StartBlock($"public {returnType} this[{conventions.GetTypeString(codeElement.IndexParameter.Type, codeElement)} position] {{ get {{"); if (parentClass.GetPropertyOfKind(CodePropertyKind.PathParameters) is CodeProperty pathParametersProp) diff --git a/src/Kiota.Builder/Writers/CSharp/CodeMethodWriter.cs b/src/Kiota.Builder/Writers/CSharp/CodeMethodWriter.cs index 289aca65d5..bdab613416 100644 --- 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($"A ", writer); + conventions.WriteAdditionalDescriptionItem($"A {conventions.GetTypeStringForDocumentation(code.ReturnType, code)}", writer); foreach (var paramWithDescription in code.Parameters .Where(static x => x.Documentation.DescriptionAvailable) .OrderBy(static x => x.Name, StringComparer.OrdinalIgnoreCase))