[OpenAPI] XML source generator does not correctly escape <see> tags

[martincostello]

Is there an existing issue for this?

• I have searched the existing issues

Describe the bug

If XML documentation comments contain content such as <see langword="true" />, it is not correctly escaped in the generated source and causes compilation to fail:

❯ dotnet build
Restore complete (0.7s)
You are using a preview version of .NET. See: https://aka.ms/dotnet-support-policy
  Repro failed with 24 error(s) (0.7s)
    C:\Coding\_scratch\obj\Debug\net10.0\Microsoft.AspNetCore.OpenApi.SourceGenerators\Microsoft.AspNetCore.OpenApi.SourceGenerators.XmlCommentGenerator\OpenApiXmlCommentSupport.generated.cs(188,368): error CS1003: Syntax error, ',' expected
    C:\Coding\_scratch\obj\Debug\net10.0\Microsoft.AspNetCore.OpenApi.SourceGenerators\Microsoft.AspNetCore.OpenApi.SourceGenerators.XmlCommentGenerator\OpenApiXmlCommentSupport.generated.cs(188,372): error CS1003: Syntax error, ',' expected
    C:\Coding\_scratch\obj\Debug\net10.0\Microsoft.AspNetCore.OpenApi.SourceGenerators\Microsoft.AspNetCore.OpenApi.SourceGenerators.XmlCommentGenerator\OpenApiXmlCommentSupport.generated.cs(188,372): error CS1010: Newline in constant
    C:\Coding\_scratch\obj\Debug\net10.0\Microsoft.AspNetCore.OpenApi.SourceGenerators\Microsoft.AspNetCore.OpenApi.SourceGenerators.XmlCommentGenerator\OpenApiXmlCommentSupport.generated.cs(189,6): error CS1003: Syntax error, ',' expected
    C:\Coding\_scratch\obj\Debug\net10.0\Microsoft.AspNetCore.OpenApi.SourceGenerators\Microsoft.AspNetCore.OpenApi.SourceGenerators.XmlCommentGenerator\OpenApiXmlCommentSupport.generated.cs(189,24): error CS1525: Invalid expression term '>'
    C:\Coding\_scratch\obj\Debug\net10.0\Microsoft.AspNetCore.OpenApi.SourceGenerators\Microsoft.AspNetCore.OpenApi.SourceGenerators.XmlCommentGenerator\OpenApiXmlCommentSupport.generated.cs(189,29): error CS1003: Syntax error, ',' expected
    C:\Coding\_scratch\obj\Debug\net10.0\Microsoft.AspNetCore.OpenApi.SourceGenerators\Microsoft.AspNetCore.OpenApi.SourceGenerators.XmlCommentGenerator\OpenApiXmlCommentSupport.generated.cs(189,37): error CS1003: Syntax error, ',' expected
    C:\Coding\_scratch\obj\Debug\net10.0\Microsoft.AspNetCore.OpenApi.SourceGenerators\Microsoft.AspNetCore.OpenApi.SourceGenerators.XmlCommentGenerator\OpenApiXmlCommentSupport.generated.cs(189,42): error CS1003: Syntax error, ',' expected
    C:\Coding\_scratch\obj\Debug\net10.0\Microsoft.AspNetCore.OpenApi.SourceGenerators\Microsoft.AspNetCore.OpenApi.SourceGenerators.XmlCommentGenerator\OpenApiXmlCommentSupport.generated.cs(189,52): error CS1003: Syntax error, ',' expected
    C:\Coding\_scratch\obj\Debug\net10.0\Microsoft.AspNetCore.OpenApi.SourceGenerators\Microsoft.AspNetCore.OpenApi.SourceGenerators.XmlCommentGenerator\OpenApiXmlCommentSupport.generated.cs(189,62): error CS1001: Identifier expected
    C:\Coding\_scratch\obj\Debug\net10.0\Microsoft.AspNetCore.OpenApi.SourceGenerators\Microsoft.AspNetCore.OpenApi.SourceGenerators.XmlCommentGenerator\OpenApiXmlCommentSupport.generated.cs(189,62): error CS1003: Syntax error, ',' expected
    C:\Coding\_scratch\obj\Debug\net10.0\Microsoft.AspNetCore.OpenApi.SourceGenerators\Microsoft.AspNetCore.OpenApi.SourceGenerators.XmlCommentGenerator\OpenApiXmlCommentSupport.generated.cs(189,62): error CS1010: Newline in constant
    C:\Coding\_scratch\obj\Debug\net10.0\Microsoft.AspNetCore.OpenApi.SourceGenerators\Microsoft.AspNetCore.OpenApi.SourceGenerators.XmlCommentGenerator\OpenApiXmlCommentSupport.generated.cs(189,87): error CS1026: ) expected
    C:\Coding\_scratch\obj\Debug\net10.0\Microsoft.AspNetCore.OpenApi.SourceGenerators\Microsoft.AspNetCore.OpenApi.SourceGenerators.XmlCommentGenerator\OpenApiXmlCommentSupport.generated.cs(189,87): error CS1003: Syntax error, ']' expected
    C:\Coding\_scratch\obj\Debug\net10.0\Microsoft.AspNetCore.OpenApi.SourceGenerators\Microsoft.AspNetCore.OpenApi.SourceGenerators.XmlCommentGenerator\OpenApiXmlCommentSupport.generated.cs(189,87): error CS1002: ; expected
    C:\Coding\_scratch\obj\Debug\net10.0\Microsoft.AspNetCore.OpenApi.SourceGenerators\Microsoft.AspNetCore.OpenApi.SourceGenerators.XmlCommentGenerator\OpenApiXmlCommentSupport.generated.cs(189,2): error CS0103: The name 'see' does not exist in the current context
    C:\Coding\_scratch\obj\Debug\net10.0\Microsoft.AspNetCore.OpenApi.SourceGenerators\Microsoft.AspNetCore.OpenApi.SourceGenerators.XmlCommentGenerator\OpenApiXmlCommentSupport.generated.cs(189,6): error CS0103: The name 'langword' does not exist in the current context
    C:\Coding\_scratch\obj\Debug\net10.0\Microsoft.AspNetCore.OpenApi.SourceGenerators\Microsoft.AspNetCore.OpenApi.SourceGenerators.XmlCommentGenerator\OpenApiXmlCommentSupport.generated.cs(189,26): error CS0103: The name 'to' does not exist in the current context
    C:\Coding\_scratch\obj\Debug\net10.0\Microsoft.AspNetCore.OpenApi.SourceGenerators\Microsoft.AspNetCore.OpenApi.SourceGenerators.XmlCommentGenerator\OpenApiXmlCommentSupport.generated.cs(189,29): error CS0103: The name 'release' does not exist in the current context
    C:\Coding\_scratch\obj\Debug\net10.0\Microsoft.AspNetCore.OpenApi.SourceGenerators\Microsoft.AspNetCore.OpenApi.SourceGenerators.XmlCommentGenerator\OpenApiXmlCommentSupport.generated.cs(189,37): error CS0103: The name 'only' does not exist in the current context
    C:\Coding\_scratch\obj\Debug\net10.0\Microsoft.AspNetCore.OpenApi.SourceGenerators\Microsoft.AspNetCore.OpenApi.SourceGenerators.XmlCommentGenerator\OpenApiXmlCommentSupport.generated.cs(189,42): error CS0103: The name 'unmanaged' does not exist in the current context
    C:\Coding\_scratch\obj\Debug\net10.0\Microsoft.AspNetCore.OpenApi.SourceGenerators\Microsoft.AspNetCore.OpenApi.SourceGenerators.XmlCommentGenerator\OpenApiXmlCommentSupport.generated.cs(189,52): error CS0103: The name 'resources' does not exist in the current context
    C:\Coding\_scratch\obj\Debug\net10.0\Microsoft.AspNetCore.OpenApi.SourceGenerators\Microsoft.AspNetCore.OpenApi.SourceGenerators.XmlCommentGenerator\OpenApiXmlCommentSupport.generated.cs(188,317): error CS1729: 'XmlParameterComment' does not contain a constructor that takes 10 arguments
    C:\Coding\_scratch\obj\Debug\net10.0\Microsoft.AspNetCore.OpenApi.SourceGenerators\Microsoft.AspNetCore.OpenApi.SourceGenerators.XmlCommentGenerator\OpenApiXmlCommentSupport.generated.cs(188,155): error CS7036: There is no argument given that corresponds to the required parameter 'Responses' of 'XmlComment.XmlComment(string?, string?, string?, string?, string?, bool, List<string>?, List<XmlParameterComment>?, List<XmlResponseComment>?)'

Build failed with 24 error(s) in 2.4s

I discovered this by chance as I had a project that contained a class that implemented IDisposable with boilerplate comments on the members implementing the interface.

Expected Behavior

The application compiles.

Steps To Reproduce

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="10.0.0-preview.2.25164.1" />
  </ItemGroup>
</Project>

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
// Learn more about configuring OpenAPI at https://aka.ms/aspnet/openapi
builder.Services.AddOpenApi();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

app.UseHttpsRedirection();

var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};

app.MapGet("/weatherforecast", () =>
{
    var forecast =  Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();
    return forecast;
})
.WithName("GetWeatherForecast");

app.Run();

record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

/// <summary>
/// A class that implements the <see cref="IDisposable"/> interface.
/// </summary>
public class MyDisposableType : IDisposable
{
    /// <summary>
    /// Finalizes an instance of the <see cref="MyDisposableType"/> class.
    /// </summary>
    ~MyDisposableType()
    {
        Dispose(false);
    }

    /// <inheritdoc />
    public void Dispose()
    {
        Dispose(true);
        GC.SuppressFinalize(this);
    }

    /// <summary>
    /// Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.
    /// </summary>
    /// <param name="disposing">
    /// <see langword="true" /> to release both managed and unmanaged resources;
    /// <see langword="false" /> to release only unmanaged resources.
    /// </param>
    protected virtual void Dispose(bool disposing)
    {
        // No-op
    }
}

Exceptions (if any)

No response

.NET Version

10.0.100-preview.2.25164.34

Anything else?

No response

[captainsafia]

@martincostello Any interest in taking a stab at fixing this bug? We'll need to update these methods to handle the langword attribute and add coverage for this in the CompletenessTests.

[dotnet-policy-service]

Looks like this issue has been identified as a candidate for community contribution. If you're considering sending a PR for this issue, look for the Summary Comment link in the issue description. That comment has been left by an engineer on our team to help you get started with handling this issue. You can learn more about our Help Wanted process here

[martincostello]

@captainsafia Sure, I can take a look.

[martincostello]

@captainsafia Just working on this now, and AFAIK the snapshot test doesn't validate that the code generated is actually valid and compilable.

Should it? Feels like it would catch more bugs that way.

Nevermind, I see now that it does, I just expected the snapshot to be verified after checking it compiled rather than before.

[captainsafia]

@martincostello Glad you got it figured out! I set it up so that you still get snapshots for uncompilable code so you can see where the errors are more easily.