Implement NormalizeDocId fix for XML comment generator

Co-authored-by: captainsafia <[email protected]>

Author: Copilot

src/OpenApi/gen/XmlCommentGenerator.Parser.cs

@@ -14,6 +14,32 @@ namespace Microsoft.AspNetCore.OpenApi.SourceGenerators;
 
 public sealed partial class XmlCommentGenerator
 {
+    /// <summary>
+    /// Normalizes a documentation comment ID to match the compiler-style format.
+    /// Strips the return type suffix for ordinary methods but retains it for conversion operators.
+    /// </summary>
+    /// <param name="docId">The documentation comment ID to normalize.</param>
+    /// <returns>The normalized documentation comment ID.</returns>
+    internal static string NormalizeDocId(string docId)
+    {
+        // Find the tilde character that indicates the return type suffix
+        var tildeIndex = docId.IndexOf('~');
+        if (tildeIndex == -1)
+        {
+            // No return type suffix, return as-is
+            return docId;
+        }
+
+        // Check if this is a conversion operator (op_Implicit or op_Explicit)
+        // For these operators, we need to keep the return type suffix
+        if (docId.Contains("op_Implicit") || docId.Contains("op_Explicit"))
+        {
+            return docId;
+        }
+
+        // For ordinary methods, strip the return type suffix
+        return docId.Substring(0, tildeIndex);
+    }
     internal static List<(string, string)> ParseXmlFile(AdditionalText additionalText, CancellationToken cancellationToken)
     {
         var text = additionalText.GetText(cancellationToken);
@@ -37,7 +63,7 @@ public sealed partial class XmlCommentGenerator
             var name = member.Attribute(DocumentationCommentXmlNames.NameAttributeName)?.Value;
             if (name is not null)
             {
-                comments.Add((name, member.ToString()));
+                comments.Add((NormalizeDocId(name), member.ToString()));
             }
         }
         return comments;
@@ -54,7 +80,7 @@ public sealed partial class XmlCommentGenerator
             if (DocumentationCommentId.CreateDeclarationId(type) is string name &&
                 type.GetDocumentationCommentXml(CultureInfo.InvariantCulture, expandIncludes: true, cancellationToken: cancellationToken) is string xml)
             {
-                comments.Add((name, xml));
+                comments.Add((NormalizeDocId(name), xml));
             }
         }
         var properties = visitor.GetPublicProperties();
@@ -63,7 +89,7 @@ public sealed partial class XmlCommentGenerator
             if (DocumentationCommentId.CreateDeclarationId(property) is string name &&
                 property.GetDocumentationCommentXml(CultureInfo.InvariantCulture, expandIncludes: true, cancellationToken: cancellationToken) is string xml)
             {
-                comments.Add((name, xml));
+                comments.Add((NormalizeDocId(name), xml));
             }
         }
         var methods = visitor.GetPublicMethods();
@@ -77,7 +103,7 @@ public sealed partial class XmlCommentGenerator
             if (DocumentationCommentId.CreateDeclarationId(method) is string name &&
                 method.GetDocumentationCommentXml(CultureInfo.InvariantCulture, expandIncludes: true, cancellationToken: cancellationToken) is string xml)
             {
-                comments.Add((name, xml));
+                comments.Add((NormalizeDocId(name), xml));
             }
         }
         return comments;

src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/XmlCommentDocumentationIdTests.cs

@@ -0,0 +1,90 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Net.Http;
+using System.Text.Json.Nodes;
+
+namespace Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests;
+
+[UsesVerify]
+public class XmlCommentDocumentationIdTests
+{
+    [Fact]
+    public async Task CanMergeXmlCommentsWithDifferentDocumentationIdFormats()
+    {
+        // This test verifies that XML comments from referenced assemblies (without return type suffix)
+        // are properly merged with in-memory symbols (with return type suffix)
+        var source = """
+using System;
+using System.Threading.Tasks;
+using Microsoft.AspNetCore.Builder;
+using Microsoft.Extensions.DependencyInjection;
+using ReferencedLibrary;
+
+var builder = WebApplication.CreateBuilder();
+
+builder.Services.AddOpenApi();
+
+var app = builder.Build();
+
+app.MapPost("/test-method", ReferencedLibrary.TestApi.TestMethod);
+
+app.Run();
+""";
+
+        var referencedLibrarySource = """
+using System;
+using System.Threading.Tasks;
+
+namespace ReferencedLibrary;
+
+public static class TestApi
+{
+    /// <summary>
+    /// This method should have its XML comment merged properly.
+    /// </summary>
+    /// <param name="id">The identifier for the test.</param>
+    /// <returns>A task representing the asynchronous operation.</returns>
+    public static Task TestMethod(int id)
+    {
+        return Task.CompletedTask;
+    }
+}
+""";
+
+        var references = new Dictionary<string, List<string>>
+        {
+            { "ReferencedLibrary", [referencedLibrarySource] }
+        };
+
+        var generator = new XmlCommentGenerator();
+        await SnapshotTestHelper.Verify(source, generator, references, out var compilation, out var additionalAssemblies);
+        await SnapshotTestHelper.VerifyOpenApi(compilation, additionalAssemblies, document =>
+        {
+            var path = document.Paths["/test-method"].Operations[HttpMethod.Post];
+            
+            // Verify that the XML comment from the referenced library was properly merged
+            // This would fail before the fix because the documentation IDs didn't match
+            Assert.NotNull(path.Summary);
+            Assert.Equal("This method should have its XML comment merged properly.", path.Summary);
+            
+            // Verify the parameter comment is also available
+            Assert.NotNull(path.Parameters);
+            Assert.Single(path.Parameters);
+            Assert.Equal("The identifier for the test.", path.Parameters[0].Description);
+        });
+    }
+
+    [Theory]
+    [InlineData("M:Sample.MyMethod(System.Int32)~System.Threading.Tasks.Task", "M:Sample.MyMethod(System.Int32)")]
+    [InlineData("M:Sample.MyMethod(System.Int32)", "M:Sample.MyMethod(System.Int32)")]
+    [InlineData("M:Sample.op_Implicit(System.Int32)~Sample.MyClass", "M:Sample.op_Implicit(System.Int32)~Sample.MyClass")]
+    [InlineData("M:Sample.op_Explicit(System.Int32)~Sample.MyClass", "M:Sample.op_Explicit(System.Int32)~Sample.MyClass")]
+    [InlineData("T:Sample.MyClass", "T:Sample.MyClass")]
+    [InlineData("P:Sample.MyClass.MyProperty", "P:Sample.MyClass.MyProperty")]
+    public void NormalizeDocId_ReturnsExpectedResult(string input, string expected)
+    {
+        var result = XmlCommentGenerator.NormalizeDocId(input);
+        Assert.Equal(expected, result);
+    }
+}