From 3540e63dd065a1a3c8d48c21c1abdfa153196287 Mon Sep 17 00:00:00 2001 From: m-nash <64171366+m-nash@users.noreply.github.com> Date: Fri, 2 Aug 2024 10:03:22 -0700 Subject: [PATCH] Add ability to turn of xml docs (#4078) Fixes https://github.com/microsoft/typespec/issues/3478 --- .../src/Configuration.cs | 19 +++- .../src/Writers/CodeWriter.cs | 2 +- .../test/ConfigurationTests.cs | 107 ++++++++++++++++-- .../test/TestHelpers/MockHelpers.cs | 5 +- .../test/TestHelpers/TestTypeProvider.cs | 12 +- .../ConfigurationTests/DisableDocsForType.cs | 10 ++ 6 files changed, 128 insertions(+), 27 deletions(-) create mode 100644 packages/http-client-csharp/generator/Microsoft.Generator.CSharp/test/Tests/TestData/ConfigurationTests/DisableDocsForType.cs diff --git a/packages/http-client-csharp/generator/Microsoft.Generator.CSharp/src/Configuration.cs b/packages/http-client-csharp/generator/Microsoft.Generator.CSharp/src/Configuration.cs index c0020bec00..2041e01a30 100644 --- a/packages/http-client-csharp/generator/Microsoft.Generator.CSharp/src/Configuration.cs +++ b/packages/http-client-csharp/generator/Microsoft.Generator.CSharp/src/Configuration.cs @@ -34,7 +34,8 @@ private Configuration( bool generateTestProject, string libraryName, bool useModelNamespace, - string libraryNamespace) + string libraryNamespace, + bool disableXmlDocs) { OutputDirectory = outputPath; AdditionalConfigOptions = additionalConfigOptions; @@ -46,6 +47,7 @@ private Configuration( UseModelNamespace = useModelNamespace; RootNamespace = libraryNamespace; ModelNamespace = useModelNamespace ? $"{libraryNamespace}.Models" : libraryNamespace; + DisableXmlDocs = disableXmlDocs; } /// @@ -60,8 +62,14 @@ private static class Options public const string LibraryName = "library-name"; public const string Namespace = "namespace"; public const string UseModelNamespace = "use-model-namespace"; + public const string DisableXmlDocs = "disable-xml-docs"; } + /// + /// Gets whether XML docs are disabled. + /// + public bool DisableXmlDocs { get; } + /// Gets the root namespace for the library. public string RootNamespace { get; } @@ -121,7 +129,7 @@ internal static Configuration Load(string outputPath, string? json = null) : JsonDocument.Parse(json).RootElement; return new Configuration( - outputPath.Equals(string.Empty) ? outputPath : Path.GetFullPath(outputPath), + Path.GetFullPath(outputPath), ParseAdditionalConfigOptions(root), ReadOption(root, Options.ClearOutputFolder), ReadOption(root, Options.GenerateModelFactory), @@ -129,7 +137,8 @@ internal static Configuration Load(string outputPath, string? json = null) ReadOption(root, Options.GenerateTestProject), ReadRequiredStringOption(root, Options.LibraryName), ReadOption(root, Options.UseModelNamespace), - ReadRequiredStringOption(root, Options.Namespace)); + ReadRequiredStringOption(root, Options.Namespace), + ReadOption(root, Options.DisableXmlDocs)); } /// @@ -141,7 +150,8 @@ internal static Configuration Load(string outputPath, string? json = null) { Options.GenerateModelFactory, true }, { Options.GenerateSampleProject, true }, { Options.ClearOutputFolder, true }, - { Options.GenerateTestProject, false } + { Options.GenerateTestProject, false }, + { Options.DisableXmlDocs, false }, }; /// @@ -156,6 +166,7 @@ internal static Configuration Load(string outputPath, string? json = null) Options.LibraryName, Options.UseModelNamespace, Options.Namespace, + Options.DisableXmlDocs, }; private static bool ReadOption(JsonElement root, string option) diff --git a/packages/http-client-csharp/generator/Microsoft.Generator.CSharp/src/Writers/CodeWriter.cs b/packages/http-client-csharp/generator/Microsoft.Generator.CSharp/src/Writers/CodeWriter.cs index 7d1417de2f..ce8dd94625 100644 --- a/packages/http-client-csharp/generator/Microsoft.Generator.CSharp/src/Writers/CodeWriter.cs +++ b/packages/http-client-csharp/generator/Microsoft.Generator.CSharp/src/Writers/CodeWriter.cs @@ -225,7 +225,7 @@ public void WriteConstructor(ConstructorProvider ctor) internal void WriteXmlDocs(XmlDocProvider? docs) { - if (docs is null) + if (CodeModelPlugin.Instance.Configuration.DisableXmlDocs || docs is null) return; if (docs.Inherit is not null) diff --git a/packages/http-client-csharp/generator/Microsoft.Generator.CSharp/test/ConfigurationTests.cs b/packages/http-client-csharp/generator/Microsoft.Generator.CSharp/test/ConfigurationTests.cs index 5efc9f04cd..5986e482a6 100644 --- a/packages/http-client-csharp/generator/Microsoft.Generator.CSharp/test/ConfigurationTests.cs +++ b/packages/http-client-csharp/generator/Microsoft.Generator.CSharp/test/ConfigurationTests.cs @@ -4,7 +4,10 @@ using System; using System.Collections.Generic; using System.IO; +using Microsoft.Generator.CSharp.Primitives; +using Microsoft.Generator.CSharp.Providers; using NUnit.Framework; +using static Microsoft.Generator.CSharp.Snippets.Snippet; namespace Microsoft.Generator.CSharp.Tests { @@ -67,15 +70,13 @@ public void TestParseConfig_OutputFolder(string mockJson, bool throwsError) [TestCaseSource("ParseConfigLibraryNameTestCases")] public void TestParseConfig_LibraryName(string mockJson, bool throwsError) { - if (throwsError) { - Assert.Throws(() => Configuration.Load(string.Empty, mockJson)); + Assert.Throws(() => MockHelpers.LoadMockPlugin(configuration: mockJson)); return; } - var configuration = Configuration.Load(string.Empty, mockJson); - var library = configuration.LibraryName; + var library = CodeModelPlugin.Instance.Configuration.LibraryName; var expected = "libraryName"; Assert.AreEqual(expected, library); @@ -87,12 +88,11 @@ public void TestParseConfig_Namespace(string mockJson, bool throwsError) { if (throwsError) { - Assert.Throws(() => Configuration.Load(string.Empty, mockJson)); + Assert.Throws(() => MockHelpers.LoadMockPlugin(configuration: mockJson)); return; } - var configuration = Configuration.Load(string.Empty, mockJson); - var ns = configuration.RootNamespace; + var ns = CodeModelPlugin.Instance.Configuration.RootNamespace; var expected = "namespace"; Assert.AreEqual(expected, ns); @@ -102,8 +102,8 @@ public void TestParseConfig_Namespace(string mockJson, bool throwsError) [TestCaseSource("ParseConfigUseModelNamespaceTestCases")] public void TestParseConfig_UseModelNamespace(string mockJson, bool expected) { - var configuration = Configuration.Load(string.Empty, mockJson); - var useModelNs = configuration.UseModelNamespace; + MockHelpers.LoadMockPlugin(configuration: mockJson); + var useModelNs = CodeModelPlugin.Instance.Configuration.UseModelNamespace; Assert.AreEqual(expected, useModelNs); } @@ -120,9 +120,9 @@ public void TestParseConfig_AdditionalConfigOptions() ""unknown-bool-property"": true }"; - var configuration = Configuration.Load(string.Empty, mockJson); + MockHelpers.LoadMockPlugin(configuration: mockJson); - var additionalConfigOptions = configuration.AdditionalConfigOptions; + var additionalConfigOptions = CodeModelPlugin.Instance.Configuration.AdditionalConfigOptions; Assert.IsNotNull(additionalConfigOptions); Assert.IsTrue(additionalConfigOptions!.ContainsKey("unknown-string-property")); Assert.IsTrue(additionalConfigOptions.ContainsKey("unknown-bool-property")); @@ -134,6 +134,91 @@ public void TestParseConfig_AdditionalConfigOptions() Assert.AreEqual(true, unknownBoolValue); } + [Test] + public void DisableDocsForProperty() + { + var mockJson = @"{ + ""output-folder"": ""outputFolder"", + ""library-name"": ""libraryName"", + ""namespace"": ""namespace"", + ""disable-xml-docs"": true + }"; + + MockHelpers.LoadMockPlugin(configuration: mockJson); + + Assert.IsTrue(CodeModelPlugin.Instance.Configuration.DisableXmlDocs); + + PropertyProvider property = new($"IntProperty description", MethodSignatureModifiers.Public, typeof(int), "IntProperty", new AutoPropertyBody(true)); + using var writer = new CodeWriter(); + writer.WriteProperty(property, true); + Assert.AreEqual("public int IntProperty { get; set; }\n", writer.ToString(false)); + } + + [Test] + public void DisableDocsForMethod() + { + var mockJson = @"{ + ""output-folder"": ""outputFolder"", + ""library-name"": ""libraryName"", + ""namespace"": ""namespace"", + ""disable-xml-docs"": true + }"; + + MockHelpers.LoadMockPlugin(configuration: mockJson); + + Assert.IsTrue(CodeModelPlugin.Instance.Configuration.DisableXmlDocs); + MethodProvider method = new( + new MethodSignature( + "Method", + $"Method Description", + MethodSignatureModifiers.Public, + null, + null, + []), + ThrowExpression(Null), + new TestTypeProvider()); + using var writer = new CodeWriter(); + writer.WriteMethod(method); + Assert.AreEqual("public void Method() => throw null;\n", writer.ToString(false)); + } + + [Test] + public void DisableDocsForType() + { + var mockJson = @"{ + ""output-folder"": ""outputFolder"", + ""library-name"": ""libraryName"", + ""namespace"": ""Test"", + ""disable-xml-docs"": true + }"; + + MockHelpers.LoadMockPlugin(configuration: mockJson); + + Assert.IsTrue(CodeModelPlugin.Instance.Configuration.DisableXmlDocs); + TypeProvider type = new TestTypeProvider(); + TypeProviderWriter writer = new(type); + Assert.AreEqual(Helpers.GetExpectedFromFile(), writer.Write().Content); + } + + [Test] + public void DisableDocsForField() + { + var mockJson = @"{ + ""output-folder"": ""outputFolder"", + ""library-name"": ""libraryName"", + ""namespace"": ""namespace"", + ""disable-xml-docs"": true + }"; + + MockHelpers.LoadMockPlugin(configuration: mockJson); + + Assert.IsTrue(CodeModelPlugin.Instance.Configuration.DisableXmlDocs); + FieldProvider field = new(FieldModifiers.Public, typeof(int), "_field", $"Field Description"); + using var writer = new CodeWriter(); + writer.WriteField(field); + Assert.AreEqual("public int _field;\n", writer.ToString(false)); + } + public static IEnumerable ParseConfigOutputFolderTestCases { get diff --git a/packages/http-client-csharp/generator/Microsoft.Generator.CSharp/test/TestHelpers/MockHelpers.cs b/packages/http-client-csharp/generator/Microsoft.Generator.CSharp/test/TestHelpers/MockHelpers.cs index 8dac7024cc..5179216db2 100644 --- a/packages/http-client-csharp/generator/Microsoft.Generator.CSharp/test/TestHelpers/MockHelpers.cs +++ b/packages/http-client-csharp/generator/Microsoft.Generator.CSharp/test/TestHelpers/MockHelpers.cs @@ -16,11 +16,12 @@ internal static class MockHelpers public static void LoadMockPlugin( Func? createCSharpTypeCore = null, - Func? createOutputLibrary = null) + Func? createOutputLibrary = null, + string? configuration = null) { var configFilePath = Path.Combine(AppContext.BaseDirectory, TestHelpersFolder); // initialize the singleton instance of the plugin - var mockPlugin = new Mock(new GeneratorContext(Configuration.Load(configFilePath))) { CallBase = true }; + var mockPlugin = new Mock(new GeneratorContext(Configuration.Load(configFilePath, configuration))) { CallBase = true }; var mockTypeFactory = new Mock() { CallBase = true }; diff --git a/packages/http-client-csharp/generator/Microsoft.Generator.CSharp/test/TestHelpers/TestTypeProvider.cs b/packages/http-client-csharp/generator/Microsoft.Generator.CSharp/test/TestHelpers/TestTypeProvider.cs index f6d466de49..27aaeb0c24 100644 --- a/packages/http-client-csharp/generator/Microsoft.Generator.CSharp/test/TestHelpers/TestTypeProvider.cs +++ b/packages/http-client-csharp/generator/Microsoft.Generator.CSharp/test/TestHelpers/TestTypeProvider.cs @@ -1,22 +1,16 @@ // Copyright (c) Microsoft Corporation. All rights reserved. // Licensed under the MIT License. -using System; using Microsoft.Generator.CSharp.Providers; namespace Microsoft.Generator.CSharp.Tests { internal class TestTypeProvider : TypeProvider { - protected override string BuildRelativeFilePath() - { - throw new NotImplementedException(); - } + protected override string BuildRelativeFilePath() => $"{Name}.cs"; + + protected override string BuildName() => "TestName"; - protected override string BuildName() - { - throw new NotImplementedException(); - } public static readonly TypeProvider Empty = new TestTypeProvider(); } } diff --git a/packages/http-client-csharp/generator/Microsoft.Generator.CSharp/test/Tests/TestData/ConfigurationTests/DisableDocsForType.cs b/packages/http-client-csharp/generator/Microsoft.Generator.CSharp/test/Tests/TestData/ConfigurationTests/DisableDocsForType.cs new file mode 100644 index 0000000000..da14431282 --- /dev/null +++ b/packages/http-client-csharp/generator/Microsoft.Generator.CSharp/test/Tests/TestData/ConfigurationTests/DisableDocsForType.cs @@ -0,0 +1,10 @@ +// + +#nullable disable + +namespace Test +{ + public partial class TestName + { + } +}