From f90c2d7af1fc1dfb5a324e92f5534359b88fcaf8 Mon Sep 17 00:00:00 2001 From: JoshLove-msft <54595583+JoshLove-msft@users.noreply.github.com> Date: Mon, 24 Feb 2025 12:11:18 -0800 Subject: [PATCH] Populate client description (#6117) Fixes https://github.com/microsoft/typespec/issues/6116 --- .../src/Providers/ClientProvider.cs | 4 ++++ .../Providers/ClientProviders/ClientProviderTests.cs | 12 ++++++++++++ .../ServiceClientWithSubClient.cs | 2 +- .../SubClientWithMultipleSubClients.cs | 2 +- .../SubClientWithSingleSubClient.cs | 2 +- .../ValidateConstructorsWhenUnsupportedAuth.cs | 2 +- .../ValidateQueryParamWriterDiff(False).cs | 2 +- .../ValidateQueryParamWriterDiff(True).cs | 2 +- .../src/Generated/UnbrandedTypeSpecClient.cs | 2 +- 9 files changed, 23 insertions(+), 7 deletions(-) diff --git a/packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator.ClientModel/src/Providers/ClientProvider.cs b/packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator.ClientModel/src/Providers/ClientProvider.cs index 0ff125a5d4e..4ff0b56a8fe 100644 --- a/packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator.ClientModel/src/Providers/ClientProvider.cs +++ b/packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator.ClientModel/src/Providers/ClientProvider.cs @@ -13,6 +13,7 @@ using Microsoft.TypeSpec.Generator.Providers; using Microsoft.TypeSpec.Generator.Snippets; using Microsoft.TypeSpec.Generator.Statements; +using Microsoft.TypeSpec.Generator.Utilities; using static Microsoft.TypeSpec.Generator.Snippets.Snippet; namespace Microsoft.TypeSpec.Generator.ClientModel.Providers @@ -48,6 +49,8 @@ private record OAuth2Fields(FieldProvider AuthField, FieldProvider Authorization private Lazy ClientOptionsParameter { get; } + protected override FormattableString Description { get; } + // for mocking #pragma warning disable CS8618 // Non-nullable field must contain a non-null value when exiting constructor. Consider declaring as nullable. protected ClientProvider() @@ -63,6 +66,7 @@ public ClientProvider(InputClient inputClient) _publicCtorDescription = $"Initializes a new instance of {Name}."; ClientOptions = new Lazy(() => _inputClient.Parent is null ? new ClientOptionsProvider(_inputClient, this) : null); ClientOptionsParameter = new Lazy(() => ClientOptions.Value != null ? ScmKnownParameters.ClientOptions(ClientOptions.Value.Type) : null); + Description = DocHelpers.GetFormattableDescription(_inputClient.Summary, _inputClient.Doc) ?? FormattableStringHelpers.Empty; var apiKey = _inputAuth?.ApiKey; var keyCredentialType = ScmCodeModelPlugin.Instance.TypeFactory.ClientPipelineApi.KeyCredentialType; diff --git a/packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator.ClientModel/test/Providers/ClientProviders/ClientProviderTests.cs b/packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator.ClientModel/test/Providers/ClientProviders/ClientProviderTests.cs index 0ac179ac1a1..a16614b3920 100644 --- a/packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator.ClientModel/test/Providers/ClientProviders/ClientProviderTests.cs +++ b/packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator.ClientModel/test/Providers/ClientProviders/ClientProviderTests.cs @@ -803,6 +803,18 @@ public void NullClientProviderIsNotAddedToLibrary() Assert.IsEmpty(plugin.Object.OutputLibrary.TypeProviders.OfType()); } + [TestCase] + public void ClientProviderSummaryIsPopulated() + { + var plugin = MockHelpers.LoadMockPlugin( + clients: () => [InputFactory.Client("test", clientNamespace: "test", doc: "client description")]); + + var client = plugin.Object.OutputLibrary.TypeProviders.OfType().SingleOrDefault(); + Assert.IsNotNull(client); + + Assert.AreEqual("/// client description. \n", client!.XmlDocs.Summary!.ToDisplayString()); + } + private static InputClient GetEnumQueryParamClient() => InputFactory.Client( TestClientName, diff --git a/packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator.ClientModel/test/Providers/ClientProviders/TestData/ClientProviderSubClientTests/ServiceClientWithSubClient.cs b/packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator.ClientModel/test/Providers/ClientProviders/TestData/ClientProviderSubClientTests/ServiceClientWithSubClient.cs index 11394c4ba14..bfb6b923875 100644 --- a/packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator.ClientModel/test/Providers/ClientProviders/TestData/ClientProviderSubClientTests/ServiceClientWithSubClient.cs +++ b/packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator.ClientModel/test/Providers/ClientProviders/TestData/ClientProviderSubClientTests/ServiceClientWithSubClient.cs @@ -6,7 +6,7 @@ namespace Sample { - /// + /// TestClient description. public partial class TestClient { /// Initializes a new instance of Animal. diff --git a/packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator.ClientModel/test/Providers/ClientProviders/TestData/ClientProviderSubClientTests/SubClientWithMultipleSubClients.cs b/packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator.ClientModel/test/Providers/ClientProviders/TestData/ClientProviderSubClientTests/SubClientWithMultipleSubClients.cs index 980e961ec35..fb66a1786d9 100644 --- a/packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator.ClientModel/test/Providers/ClientProviders/TestData/ClientProviderSubClientTests/SubClientWithMultipleSubClients.cs +++ b/packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator.ClientModel/test/Providers/ClientProviders/TestData/ClientProviderSubClientTests/SubClientWithMultipleSubClients.cs @@ -6,7 +6,7 @@ namespace Sample { - /// + /// AnimalClient description. public partial class Animal { /// Initializes a new instance of Dog. diff --git a/packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator.ClientModel/test/Providers/ClientProviders/TestData/ClientProviderSubClientTests/SubClientWithSingleSubClient.cs b/packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator.ClientModel/test/Providers/ClientProviders/TestData/ClientProviderSubClientTests/SubClientWithSingleSubClient.cs index bfd46e1cb4e..273c195bac9 100644 --- a/packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator.ClientModel/test/Providers/ClientProviders/TestData/ClientProviderSubClientTests/SubClientWithSingleSubClient.cs +++ b/packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator.ClientModel/test/Providers/ClientProviders/TestData/ClientProviderSubClientTests/SubClientWithSingleSubClient.cs @@ -6,7 +6,7 @@ namespace Sample { - /// + /// DogClient description. public partial class Dog { /// Initializes a new instance of Husky. diff --git a/packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator.ClientModel/test/Providers/ClientProviders/TestData/ClientProviderTests/ValidateConstructorsWhenUnsupportedAuth.cs b/packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator.ClientModel/test/Providers/ClientProviders/TestData/ClientProviderTests/ValidateConstructorsWhenUnsupportedAuth.cs index c305fb0c93d..a559b4e2b16 100644 --- a/packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator.ClientModel/test/Providers/ClientProviders/TestData/ClientProviderTests/ValidateConstructorsWhenUnsupportedAuth.cs +++ b/packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator.ClientModel/test/Providers/ClientProviders/TestData/ClientProviderTests/ValidateConstructorsWhenUnsupportedAuth.cs @@ -7,7 +7,7 @@ namespace Sample { - /// + /// TestClient description. public partial class TestClient { internal TestClient(global::System.Uri endpoint) : this(endpoint, new global::Sample.TestClientOptions()) diff --git a/packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator.ClientModel/test/Providers/ClientProviders/TestData/ClientProviderTests/ValidateQueryParamWriterDiff(False).cs b/packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator.ClientModel/test/Providers/ClientProviders/TestData/ClientProviderTests/ValidateQueryParamWriterDiff(False).cs index 594dd3d1626..c625d31ca17 100644 --- a/packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator.ClientModel/test/Providers/ClientProviders/TestData/ClientProviderTests/ValidateQueryParamWriterDiff(False).cs +++ b/packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator.ClientModel/test/Providers/ClientProviders/TestData/ClientProviderTests/ValidateQueryParamWriterDiff(False).cs @@ -9,7 +9,7 @@ namespace Sample { - /// + /// TestClient description. public partial class TestClient { public virtual global::System.ClientModel.ClientResult Operation(global::Sample.Models.InputEnum queryParam, global::System.Threading.CancellationToken cancellationToken = default) diff --git a/packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator.ClientModel/test/Providers/ClientProviders/TestData/ClientProviderTests/ValidateQueryParamWriterDiff(True).cs b/packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator.ClientModel/test/Providers/ClientProviders/TestData/ClientProviderTests/ValidateQueryParamWriterDiff(True).cs index 0a508c898aa..fd1f279e860 100644 --- a/packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator.ClientModel/test/Providers/ClientProviders/TestData/ClientProviderTests/ValidateQueryParamWriterDiff(True).cs +++ b/packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator.ClientModel/test/Providers/ClientProviders/TestData/ClientProviderTests/ValidateQueryParamWriterDiff(True).cs @@ -10,7 +10,7 @@ namespace Sample { - /// + /// TestClient description. public partial class TestClient { public virtual async global::System.Threading.Tasks.Task OperationAsync(global::Sample.Models.InputEnum queryParam, global::System.Threading.CancellationToken cancellationToken = default) diff --git a/packages/http-client-csharp/generator/TestProjects/Local/Unbranded-TypeSpec/src/Generated/UnbrandedTypeSpecClient.cs b/packages/http-client-csharp/generator/TestProjects/Local/Unbranded-TypeSpec/src/Generated/UnbrandedTypeSpecClient.cs index 842713308c5..6871e5d3ae6 100644 --- a/packages/http-client-csharp/generator/TestProjects/Local/Unbranded-TypeSpec/src/Generated/UnbrandedTypeSpecClient.cs +++ b/packages/http-client-csharp/generator/TestProjects/Local/Unbranded-TypeSpec/src/Generated/UnbrandedTypeSpecClient.cs @@ -13,7 +13,7 @@ namespace UnbrandedTypeSpec { - /// + /// This is a sample typespec project. public partial class UnbrandedTypeSpecClient { private readonly Uri _endpoint;