[Bug] Broken HTML for <code> from inherited xml-comment

[bkoelman]

Describe the bug When using /// <inheritdoc /> on a class property that implements an interface, its example code is escaped twice, resulting in broken HTML.

To Reproduce Steps to reproduce the behavior:

1. Download the zip file below, which contains a minimal repro project DocfxEscapeBugRepro.zip
2. Run dotnet tool restore
3. Run dotnet docfx docs/docfx.json --serve
4. Open http://localhost:8080 in your browser
5. Click API > IJsonApiOptions
6. Observe the example HTML is rendered properly
7. Click JsonApiOptions
8. Observe the example HTML is broken

Expected behavior Example code is rendered properly on both pages.

Context (please complete the following information):

• OS: Windows 11
• Docfx version: 2.75.3
• .NET version: .NET 8
• docfx.json config: as produced by dotnet docfx init, see zip file
• Exceptions: none
• Errors and warnings: none
• .NET info:

.NET SDK:
 Version:           8.0.201
 Commit:            4c2d78f037
 Workload version:  8.0.200-manifests.e575128c

Runtime Environment:
 OS Name:     Windows
 OS Version:  10.0.22631
 OS Platform: Windows
 RID:         win-x64
 Base Path:   C:\Program Files\dotnet\sdk\8.0.201\

.NET workloads installed:
There are no installed workloads to display.

Host:
  Version:      8.0.2
  Architecture: x64
  Commit:       1381d5ebd2

.NET SDKs installed:
  8.0.200 [C:\Program Files\dotnet\sdk]
  8.0.201 [C:\Program Files\dotnet\sdk]

.NET runtimes installed:
  Microsoft.AspNetCore.App 6.0.27 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App]
  Microsoft.AspNetCore.App 8.0.2 [C:\Program Files\dotnet\shared\Microsoft.AspNetCore.App]
  Microsoft.NETCore.App 6.0.27 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
  Microsoft.NETCore.App 8.0.2 [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
  Microsoft.WindowsDesktop.App 6.0.27 [C:\Program Files\dotnet\shared\Microsoft.WindowsDesktop.App]
  Microsoft.WindowsDesktop.App 8.0.2 [C:\Program Files\dotnet\shared\Microsoft.WindowsDesktop.App]

Other architectures found:
  x86   [C:\Program Files (x86)\dotnet]
    registered at [HKLM\SOFTWARE\dotnet\Setup\InstalledVersions\x86\InstallLocation]

Environment variables:
  Not set

global.json file:
  Not found

Additional context I've been debugging through the docfx sources and found that since v2.74.1 (which introduced this bug), Docfx.Dotnet.XmlComment.ResolveCode() was changed to wrap <code> into a <pre> node. I suspect this isn't the right place to do that, because it seems that mustache applies escaping as well, though I'm not entirely sure where that happens. I haven't been able to trace exactly where the double escaping originates from.

Any pointers to investigate further would be appreciated.

[filzrev]

As a temporary workaround. It can be fixed by adding following line at XmlComment.Parse method.

xml = XElement.Parse(xml).ToString(SaveOptions.None);

It seems symbol.GetDocumentationComment returns slightly different xml for <inheritdoc/> element. And docfx failed to parse these xml comment.

By applying XML formatting with SaveOptions.None before processing this issue can be avoided. (When using SaveOptions.DisableFormatting is used. result html is broken)

[filzrev]

Reported issues (#9495/#9736) are expected to be fixed with latest docfx version (v2.76.0).

@bkoelman Is it able to confirms problems are fixed in latest version?

[bkoelman]

Yes, the latest release (v2.76.0) fixes these. Both issues can be closed. Thanks!