Suppress CS1591 when generating CSharp code and documentation is not available

CHANGELOG.md

@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Suppress CS1591 when generating CSharp code and documentation is not available
+
 ### Changed
 
 - Changed URI template generation to reuse templates when required templates are absent across operations.

src/Kiota.Builder/Writers/CSharp/CSharpConventionService.cs

@@ -39,28 +39,29 @@ public static void WriteNullableClosing(LanguageWriter writer)
     private const string ReferenceTypePrefix = "<see cref=\"";
     private const string ReferenceTypeSuffix = "\"/>";
 #pragma warning disable S1006 // Method overrides should not change parameter defaults
-    public override void WriteShortDescription(IDocumentedElement element, LanguageWriter writer, string prefix = "<summary>", string suffix = "</summary>")
+    public override bool WriteShortDescription(IDocumentedElement element, LanguageWriter writer, string prefix = "<summary>", string suffix = "</summary>")
 #pragma warning restore S1006 // Method overrides should not change parameter defaults
     {
         ArgumentNullException.ThrowIfNull(writer);
         ArgumentNullException.ThrowIfNull(element);
-        if (element is not CodeElement codeElement) return;
-        if (!element.Documentation.DescriptionAvailable) return;
+        if (element is not CodeElement codeElement) return false;
+        if (!element.Documentation.DescriptionAvailable) return false;
         var description = element.Documentation.GetDescription(type => GetTypeStringForDocumentation(type, codeElement), normalizationFunc: static x => x.CleanupXMLString());
         writer.WriteLine($"{DocCommentPrefix}{prefix}{description}{suffix}");
+        return true;
     }
     public void WriteAdditionalDescriptionItem(string description, LanguageWriter writer)
     {
         ArgumentNullException.ThrowIfNull(writer);
         ArgumentNullException.ThrowIfNull(description);
         writer.WriteLine($"{DocCommentPrefix}{description}");
     }
-    public void WriteLongDescription(IDocumentedElement element, LanguageWriter writer)
+    public bool WriteLongDescription(IDocumentedElement element, LanguageWriter writer)
     {
         ArgumentNullException.ThrowIfNull(writer);
         ArgumentNullException.ThrowIfNull(element);
-        if (element.Documentation is not { } documentation) return;
-        if (element is not CodeElement codeElement) return;
+        if (element.Documentation is not { } documentation) return false;
+        if (element is not CodeElement codeElement) return false;
         if (documentation.DescriptionAvailable || documentation.ExternalDocumentationAvailable)
         {
             writer.WriteLine($"{DocCommentPrefix}<summary>");
@@ -72,7 +73,9 @@ public void WriteLongDescription(IDocumentedElement element, LanguageWriter writ
             if (documentation.ExternalDocumentationAvailable)
                 writer.WriteLine($"{DocCommentPrefix}{documentation.DocumentationLabel} <see href=\"{documentation.DocumentationLink}\" />");
             writer.WriteLine($"{DocCommentPrefix}</summary>");
+            return true;
         }
+        return false;
     }
     public override string GetAccessModifier(AccessModifier access)
     {

src/Kiota.Builder/Writers/CSharp/CodeClassDeclarationWriter.cs

@@ -35,9 +35,11 @@ public override void WriteCodeElement(ClassDeclaration codeElement, LanguageWrit
                                         .Select(static x => x.ToFirstCharacterUpperCase())
                                         .ToArray();
         var derivation = derivedTypes.Length != 0 ? ": " + derivedTypes.Aggregate(static (x, y) => $"{x}, {y}") + " " : string.Empty;
-        conventions.WriteLongDescription(parentClass, writer);
+        bool hasDescription = conventions.WriteLongDescription(parentClass, writer);
         conventions.WriteDeprecationAttribute(parentClass, writer);
+        if (!hasDescription) writer.WriteLine("#pragma warning disable CS1591");
         writer.WriteLine($"public class {codeElement.Name.ToFirstCharacterUpperCase()} {derivation}");
+        if (!hasDescription) writer.WriteLine("#pragma warning restore CS1591");
         writer.StartBlock();
     }
 }

src/Kiota.Builder/Writers/CSharp/CodeEnumWriter.cs

@@ -29,22 +29,26 @@ public override void WriteCodeElement(CodeEnum codeElement, LanguageWriter write
                 writer.WriteLine(x);
             writer.StartBlock($"namespace {codeNamespace.Name} {{");
         }
-        conventions.WriteShortDescription(codeElement, writer);
+        bool hasDescription = conventions.WriteShortDescription(codeElement, writer);
         if (codeElement.Flags)
             writer.WriteLine("[Flags]");
         conventions.WriteDeprecationAttribute(codeElement, writer);
+        if (!hasDescription) writer.WriteLine("#pragma warning disable CS1591");
         writer.WriteLine($"public enum {codeElement.Name.ToFirstCharacterUpperCase()}");
+        if (!hasDescription) writer.WriteLine("#pragma warning restore CS1591");
         writer.StartBlock();
         var idx = 0;
         foreach (var option in codeElement.Options)
         {
-            conventions.WriteShortDescription(option, writer);
+            hasDescription = conventions.WriteShortDescription(option, writer);
 
             if (option.IsNameEscaped)
             {
                 writer.WriteLine($"[EnumMember(Value = \"{option.SerializationName}\")]");
             }
+            if (!hasDescription) writer.WriteLine("#pragma warning disable CS1591");
             writer.WriteLine($"{option.Name.ToFirstCharacterUpperCase()}{(codeElement.Flags ? " = " + GetEnumFlag(idx) : string.Empty)},");
+            if (!hasDescription) writer.WriteLine("#pragma warning restore CS1591");
             idx++;
         }
         if (codeNamespace != null)

src/Kiota.Builder/Writers/CommonLanguageConventionService.cs

@@ -41,5 +41,5 @@ public string TranslateType(CodeTypeBase type)
     }
 
     public abstract string TranslateType(CodeType type);
-    public abstract void WriteShortDescription(IDocumentedElement element, LanguageWriter writer, string prefix = "", string suffix = "");
+    public abstract bool WriteShortDescription(IDocumentedElement element, LanguageWriter writer, string prefix = "", string suffix = "");
 }

src/Kiota.Builder/Writers/Go/GoConventionService.cs

@@ -168,19 +168,20 @@ currentEnumDefinition.Parent is CodeNamespace enumNS &&
         return string.Empty;
     }
 
-    public override void WriteShortDescription(IDocumentedElement element, LanguageWriter writer, string prefix = "", string suffix = "")
+    public override bool WriteShortDescription(IDocumentedElement element, LanguageWriter writer, string prefix = "", string suffix = "")
     {
         ArgumentNullException.ThrowIfNull(writer);
         ArgumentNullException.ThrowIfNull(element);
-        if (!element.Documentation.DescriptionAvailable) return;
-        if (element is not CodeElement codeElement) return;
+        if (!element.Documentation.DescriptionAvailable) return false;
+        if (element is not CodeElement codeElement) return false;
 
         var description = element.Documentation.GetDescription(x => GetTypeString(x, codeElement, true, false));
         if (!string.IsNullOrEmpty(prefix))
         {
             description = description.ToFirstCharacterLowerCase();
         }
         WriteDescriptionItem($"{prefix}{description}{suffix}", writer);
+        return true;
     }
     public void WriteDescriptionItem(string description, LanguageWriter writer)
     {

src/Kiota.Builder/Writers/ILanguageConventionService.cs

@@ -27,5 +27,5 @@ string TempDictionaryVarName
     string GetTypeString(CodeTypeBase code, CodeElement targetElement, bool includeCollectionInformation = true, LanguageWriter? writer = null);
     string TranslateType(CodeType type);
     string GetParameterSignature(CodeParameter parameter, CodeElement targetElement, LanguageWriter? writer = null);
-    void WriteShortDescription(IDocumentedElement element, LanguageWriter writer, string prefix = "", string suffix = "");
+    bool WriteShortDescription(IDocumentedElement element, LanguageWriter writer, string prefix = "", string suffix = "");
 }

src/Kiota.Builder/Writers/Java/JavaConventionService.cs

@@ -98,16 +98,18 @@ internal string GetReturnDocComment(string returnType)
     }
     private const string ReferenceTypePrefix = "{@link ";
     private const string ReferenceTypeSuffix = "}";
-    public override void WriteShortDescription(IDocumentedElement element, LanguageWriter writer, string prefix = "", string suffix = "")
+    public override bool WriteShortDescription(IDocumentedElement element, LanguageWriter writer, string prefix = "", string suffix = "")
     {
         ArgumentNullException.ThrowIfNull(writer);
         ArgumentNullException.ThrowIfNull(element);
-        if (!element.Documentation.DescriptionAvailable) return;
-        if (element is not CodeElement codeElement) return;
+        if (!element.Documentation.DescriptionAvailable) return false;
+        if (element is not CodeElement codeElement) return false;
 
         var description = element.Documentation.GetDescription(x => GetTypeReferenceForDocComment(x, codeElement), ReferenceTypePrefix, ReferenceTypeSuffix, RemoveInvalidDescriptionCharacters);
 
         writer.WriteLine($"{DocCommentStart} {description}{DocCommentEnd}");
+
+        return true;
     }
     internal string GetTypeReferenceForDocComment(CodeTypeBase code, CodeElement targetElement)
     {

src/Kiota.Builder/Writers/Php/PhpConventionService.cs

@@ -136,18 +136,20 @@ private string GetCollectionDocString(CodeParameter codeParameter)
     }
 
     internal static string RemoveInvalidDescriptionCharacters(string originalDescription) => originalDescription.Replace("\\", "/", StringComparison.OrdinalIgnoreCase);
-    public override void WriteShortDescription(IDocumentedElement element, LanguageWriter writer, string prefix = "", string suffix = "")
+    public override bool WriteShortDescription(IDocumentedElement element, LanguageWriter writer, string prefix = "", string suffix = "")
     {
         ArgumentNullException.ThrowIfNull(writer);
         ArgumentNullException.ThrowIfNull(element);
-        if (!element.Documentation.DescriptionAvailable) return;
-        if (element is not CodeElement codeElement) return;
+        if (!element.Documentation.DescriptionAvailable) return false;
+        if (element is not CodeElement codeElement) return false;
 
         var description = element.Documentation.GetDescription(type => GetTypeString(type, codeElement), normalizationFunc: RemoveInvalidDescriptionCharacters);
 
         writer.WriteLine(DocCommentStart);
         writer.WriteLine($"{DocCommentPrefix}{description}");
         writer.WriteLine(DocCommentEnd);
+
+        return true;
     }
 
     public void WriteLongDescription(IDocumentedElement element, LanguageWriter writer, IEnumerable<string>? additionalRemarks = default)

src/Kiota.Builder/Writers/Python/PythonConventionService.cs

@@ -155,17 +155,19 @@ private string WriteInlineDeclaration(CodeType currentType, CodeElement targetEl
             return "object";
         return $"{{{innerDeclaration}}}";
     }
-    public override void WriteShortDescription(IDocumentedElement element, LanguageWriter writer, string prefix = "", string suffix = "")
+    public override bool WriteShortDescription(IDocumentedElement element, LanguageWriter writer, string prefix = "", string suffix = "")
     {
         ArgumentNullException.ThrowIfNull(writer);
         ArgumentNullException.ThrowIfNull(element);
-        if (!element.Documentation.DescriptionAvailable) return;
-        if (element is not CodeElement codeElement) return;
+        if (!element.Documentation.DescriptionAvailable) return false;
+        if (element is not CodeElement codeElement) return false;
 
         var description = element.Documentation.GetDescription(type => GetTypeString(type, codeElement), normalizationFunc: RemoveInvalidDescriptionCharacters);
         writer.WriteLine(DocCommentStart);
         writer.WriteLine(description);
         writer.WriteLine(DocCommentEnd);
+
+        return true;
     }
     public void WriteLongDescription(IDocumentedElement element, LanguageWriter writer, IEnumerable<string>? additionalRemarks = default)
     {

src/Kiota.Builder/Writers/Ruby/RubyConventionService.cs

@@ -52,16 +52,18 @@ public override string TranslateType(CodeType type)
             _ => type.Name.ToFirstCharacterUpperCase() is string typeName && !string.IsNullOrEmpty(typeName) ? typeName : "object",
         };
     }
-    public override void WriteShortDescription(IDocumentedElement element, LanguageWriter writer, string prefix = "", string suffix = "")
+    public override bool WriteShortDescription(IDocumentedElement element, LanguageWriter writer, string prefix = "", string suffix = "")
     {
         ArgumentNullException.ThrowIfNull(writer);
         ArgumentNullException.ThrowIfNull(element);
-        if (!element.Documentation.DescriptionAvailable) return;
-        if (element is not CodeElement codeElement) return;
+        if (!element.Documentation.DescriptionAvailable) return false;
+        if (element is not CodeElement codeElement) return false;
 
         var description = element.Documentation.GetDescription(type => GetTypeString(type, codeElement));
         writer.WriteLine($"{DocCommentPrefix}");
         writer.WriteLine($"# {description}");
+
+        return true;
     }
 #pragma warning disable CA1822 // Method should be static
     public string GetNormalizedNamespacePrefixForType(CodeTypeBase type)

src/Kiota.Builder/Writers/Swift/SwiftConventionService.cs

@@ -20,15 +20,17 @@ public SwiftConventionService(string clientNamespaceName)
     public static readonly char NullableMarker = '?';
     public static string NullableMarkerAsString => "?";
     public override string ParseNodeInterfaceName => "ParseNode";
-    public override void WriteShortDescription(IDocumentedElement element, LanguageWriter writer, string prefix = "<summary>", string suffix = "</summary>")
+    public override bool WriteShortDescription(IDocumentedElement element, LanguageWriter writer, string prefix = "<summary>", string suffix = "</summary>")
     {
         ArgumentNullException.ThrowIfNull(writer);
         ArgumentNullException.ThrowIfNull(element);
-        if (!element.Documentation.DescriptionAvailable) return;
-        if (element is not CodeElement codeElement) return;
+        if (!element.Documentation.DescriptionAvailable) return false;
+        if (element is not CodeElement codeElement) return false;
 
         var description = element.Documentation.GetDescription(type => GetTypeString(type, codeElement));
         writer.WriteLine($"{DocCommentPrefix}{prefix}{description}{prefix}");
+
+        return true;
     }
     public override string GetAccessModifier(AccessModifier access)
     {

src/Kiota.Builder/Writers/TypeScript/TypeScriptConventionService.cs

@@ -132,15 +132,17 @@ public bool IsPrimitiveType(string typeName)
     }
 #pragma warning restore CA1822 // Method should be static
     internal static string RemoveInvalidDescriptionCharacters(string originalDescription) => originalDescription?.Replace("\\", "/", StringComparison.OrdinalIgnoreCase) ?? string.Empty;
-    public override void WriteShortDescription(IDocumentedElement element, LanguageWriter writer, string prefix = "", string suffix = "")
+    public override bool WriteShortDescription(IDocumentedElement element, LanguageWriter writer, string prefix = "", string suffix = "")
     {
         ArgumentNullException.ThrowIfNull(writer);
         ArgumentNullException.ThrowIfNull(element);
-        if (!element.Documentation.DescriptionAvailable) return;
-        if (element is not CodeElement codeElement) return;
+        if (!element.Documentation.DescriptionAvailable) return false;
+        if (element is not CodeElement codeElement) return false;
 
         var description = element.Documentation.GetDescription(type => GetTypeString(type, codeElement), ReferenceTypePrefix, ReferenceTypeSuffix, RemoveInvalidDescriptionCharacters);
         writer.WriteLine($"{DocCommentStart} {description}{DocCommentEnd}");
+
+        return true;
     }
     internal const string ReferenceTypePrefix = "{@link ";
     internal const string ReferenceTypeSuffix = "}";