Fix null reference and XML escaping in XmlDocumentationGenerator

[Copilot]

Description:

Addresses review feedback from PR #887 regarding null safety and XML encoding in XML documentation generation.

Null Reference Fix:

• Added null-conditional operator for document.Tags access to prevent NullReferenceException when OpenAPI document has no tags

XML Escaping Enhancement:

• Extended EscapeSymbols method to escape & character (in addition to existing < and >)
• Ensures proper encoding order: ampersand first, then angle brackets, to avoid double-escaping
• Prevents malformed XML when documentation contains special characters

Test Coverage:

• Can_Handle_Null_Document_Tags - validates safe handling of null tags collection
• Can_Escape_Xml_Special_Characters_In_Interface_Doc - verifies XML entity encoding in interface summaries
• Can_Escape_Xml_Special_Characters_In_Method_Summary - verifies XML entity encoding in method documentation

Example OpenAPI Specifications:

openapi: 3.0.0
info:
  title: Test API
paths:
  /users:
    get:
      summary: Get users <admin> & filter
      tags:
        - Users
      responses:
        '200':
          description: Success

Example generated Refit interface

Before:

/// <summary>Get users <admin> & filter</summary>  // Invalid XML
[Get("/users")]
Task GetUsers();

After:

/// <summary>Get users &lt;admin&gt; &amp; filter</summary>  // Valid XML
[Get("/users")]
Task GetUsers();

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• collector.exceptionless.io
  • Triggering command: /home/REDACTED/work/refitter/refitter/src/Refitter.Tests/bin/Release/net8.0/Refitter.Tests /home/REDACTED/work/refitter/refitter/src/Refitter.Tests/bin/Release/net8.0/Refitter.Tests --server dotnettestcli --dotnet-test-pipe /tmp/d7f4e169f85e40a6a990ba2a40dd3467 (dns block)
  • Triggering command: /home/REDACTED/work/refitter/refitter/src/Refitter.Tests/bin/Release/net8.0/Refitter.Tests /home/REDACTED/work/refitter/refitter/src/Refitter.Tests/bin/Release/net8.0/Refitter.Tests --server dotnettestcli --dotnet-test-pipe /tmp/cc8db2bd32014527829c9449c50731fa 607570477388aac361639dd7b0/Project.csproj (dns block)
• config.exceptionless.io
  • Triggering command: /home/REDACTED/work/refitter/refitter/src/Refitter.Tests/bin/Release/net8.0/Refitter.Tests /home/REDACTED/work/refitter/refitter/src/Refitter.Tests/bin/Release/net8.0/Refitter.Tests --server dotnettestcli --dotnet-test-pipe /tmp/d7f4e169f85e40a6a990ba2a40dd3467 (dns block)
  • Triggering command: /home/REDACTED/work/refitter/refitter/src/Refitter.Tests/bin/Release/net8.0/Refitter.Tests /home/REDACTED/work/refitter/refitter/src/Refitter.Tests/bin/Release/net8.0/Refitter.Tests --server dotnettestcli --dotnet-test-pipe /tmp/cc8db2bd32014527829c9449c50731fa 607570477388aac361639dd7b0/Project.csproj (dns block)
• developers.intellihr.io
  • Triggering command: /home/REDACTED/work/refitter/refitter/src/Refitter.Tests/bin/Release/net8.0/Refitter.Tests /home/REDACTED/work/refitter/refitter/src/Refitter.Tests/bin/Release/net8.0/Refitter.Tests --server dotnettestcli --dotnet-test-pipe /tmp/d7f4e169f85e40a6a990ba2a40dd3467 (dns block)
  • Triggering command: /home/REDACTED/work/refitter/refitter/src/Refitter.Tests/bin/Release/net8.0/Refitter.Tests /home/REDACTED/work/refitter/refitter/src/Refitter.Tests/bin/Release/net8.0/Refitter.Tests --server dotnettestcli --dotnet-test-pipe /tmp/cc8db2bd32014527829c9449c50731fa 607570477388aac361639dd7b0/Project.csproj (dns block)
• heartbeat.exceptionless.io
  • Triggering command: /home/REDACTED/work/refitter/refitter/src/Refitter.Tests/bin/Release/net8.0/Refitter.Tests /home/REDACTED/work/refitter/refitter/src/Refitter.Tests/bin/Release/net8.0/Refitter.Tests --server dotnettestcli --dotnet-test-pipe /tmp/d7f4e169f85e40a6a990ba2a40dd3467 (dns block)
  • Triggering command: /home/REDACTED/work/refitter/refitter/src/Refitter.Tests/bin/Release/net8.0/Refitter.Tests /home/REDACTED/work/refitter/refitter/src/Refitter.Tests/bin/Release/net8.0/Refitter.Tests --server dotnettestcli --dotnet-test-pipe /tmp/cc8db2bd32014527829c9449c50731fa 607570477388aac361639dd7b0/Project.csproj (dns block)
• petstore.swagger.io
  • Triggering command: /home/REDACTED/work/refitter/refitter/src/Refitter.Tests/bin/Release/net8.0/Refitter.Tests /home/REDACTED/work/refitter/refitter/src/Refitter.Tests/bin/Release/net8.0/Refitter.Tests --server dotnettestcli --dotnet-test-pipe /tmp/d7f4e169f85e40a6a990ba2a40dd3467 (dns block)
  • Triggering command: /home/REDACTED/work/refitter/refitter/src/Refitter.Tests/bin/Release/net8.0/Refitter.Tests /home/REDACTED/work/refitter/refitter/src/Refitter.Tests/bin/Release/net8.0/Refitter.Tests --server dotnettestcli --dotnet-test-pipe /tmp/cc8db2bd32014527829c9449c50731fa 607570477388aac361639dd7b0/Project.csproj (dns block)
• petstore3.swagger.io
  • Triggering command: /home/REDACTED/work/refitter/refitter/src/Refitter.Tests/bin/Release/net8.0/Refitter.Tests /home/REDACTED/work/refitter/refitter/src/Refitter.Tests/bin/Release/net8.0/Refitter.Tests --server dotnettestcli --dotnet-test-pipe /tmp/d7f4e169f85e40a6a990ba2a40dd3467 (dns block)
  • Triggering command: /home/REDACTED/work/refitter/refitter/src/Refitter.Tests/bin/Release/net8.0/Refitter.Tests /home/REDACTED/work/refitter/refitter/src/Refitter.Tests/bin/Release/net8.0/Refitter.Tests --server dotnettestcli --dotnet-test-pipe /tmp/cc8db2bd32014527829c9449c50731fa 607570477388aac361639dd7b0/Project.csproj (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

Apply changes based on the comments in this thread

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.33%. Comparing base (f049330) to head (9a8b9de).
⚠️ Report is 7 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #890   +/-   ##
=======================================
  Coverage   93.33%   93.33%           
=======================================
  Files          23       23           
  Lines        1395     1396    +1     
=======================================
+ Hits         1302     1303    +1     
  Misses         47       47           
  Partials       46       46           

Flag	Coverage Δ
unittests	93.33% <100.00%> (+<0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

Improves XML documentation generation robustness by preventing null dereferences when OpenAPI documents omit tags and by producing well-formed XML docs when summaries/descriptions contain special characters.

Changes:

• Add null-safe access for document.Tags when generating interface documentation by tag.
• Extend XML escaping to include & (with safe replacement ordering).
• Add/adjust tests and update generated snapshot output accordingly.

Reviewed changes

Copilot reviewed 3 out of 4 changed files in this pull request and generated 1 comment.

File	Description
src/Refitter.Core/XmlDocumentationGenerator.cs	Makes tag lookup null-safe and escapes ampersands in XML doc text.
src/Refitter.Tests/XmlDocumentationGeneratorTests.cs	Adds regression tests for null tags and XML escaping in interface/method summaries.
src/Refitter.Tests/Examples/NumericFormatWithPatternTests.cs	Removes BOM/normalizes file header formatting.
src/Refitter.SourceGenerator.Tests/AdditionalFiles/Generated/SwaggerPetstoreMultipleInterfaces.g.cs	Updates generated baseline to reflect new documentation output.

Comments suppressed due to low confidence (1)

src/Refitter.Core/XmlDocumentationGenerator.cs:138

• This foreach loop implicitly filters its target sequence - consider filtering the sequence explicitly using '.Where(...)'.

        foreach (var parameter in method.Parameters)
        {
            if (parameter == null)
                continue;

            var description = parameter.HasDescription
                ? parameter.Description
                : $"{parameter.VariableName} parameter";

            this.AppendXmlCommentBlock(
                "param",
                description,
                code,
                new Dictionary<string, string>
                {
                    ["name"] = parameter.VariableName
                });
        }

[Copilot]

EscapeSymbols now escapes ampersands, but several XML doc blocks still write OpenAPI-provided text without escaping (e.g., <param> uses parameter.Description directly). This means parameter descriptions containing &, <, or > can still generate malformed XML documentation and trigger compiler warnings/errors. Consider applying escaping to OpenAPI-sourced parameter/response description text before passing it into AppendXmlCommentBlock (while preserving intentionally-generated XML markup like <see/> and <list>).