Fix invalid C# syntax and dead links for ref/out/in parameters in rendered docs

[Malcolmnixon]

Summary

Fixes a rendering bug remaining after #40: although the coverage-checker
false-positive on ref/out/in parameters was fixed by translating
Mono.Cecil's byref marker in ToXmlDocTypeName, the doc-rendering path
never handled byref parameters at all, so generated pages for such methods
still showed invalid C# and dead links.

Repro (before fix)

For a method like TryResolve(string, out NaturalLanguageAudioTag, out NaturalLanguageAudioTagKind):

public static bool TryResolve(string rawBracketContent, NaturalLanguageAudioTag& tag, NaturalLanguageAudioTagKind& kind)

| tag | [NaturalLanguageAudioTag&](../NaturalLanguageAudioTag&.md) | ... |

• Invalid C# — no out keyword, and & is not legal in a type reference.
• Dead link — NaturalLanguageAudioTag&.md never exists; the real page is NaturalLanguageAudioTag.md.

Root cause

Three separate rendering code paths never handled Mono.Cecil's ByReferenceType:

1. TypeNameSimplifier.SimplifyCore had no case for it, so it fell to the
   default arm and preserved the raw trailing &.
2. TypeLinkResolver.Linkify had no case for it either, so link targets were
   computed from that same &-suffixed name.
3. None of DotNetEmitter's signature builders (BuildMethodSignature,
   BuildMethodDisplayName, BuildOperatorSignature, BuildDelegateSignature)
   ever emitted the out/ref/in keyword.

Fix

• TypeNameSimplifier.SimplifyCore: added a byref-unwrapping rule that
  simplifies a ByReferenceType by recursing into its ElementType.
• TypeLinkResolver.Linkify: added the same unwrap so link text/href use the
  un-suffixed type name and link to the real page.
• DotNetEmitter: added GetRefKindKeyword(ParameterDefinition) returning
  "out ", "in ", "ref ", or "" based on IsOut/IsIn. Prepended it to
  the parameter type in all four signature builders.
• DotNetEmitterGradualDisclosure / DotNetEmitterSingleFile: parameter
  table rows now prepend the ref-kind keyword before the linkified type.

After fix

public static bool TryResolve(string rawBracketContent, out NaturalLanguageAudioTag tag, out NaturalLanguageAudioTagKind kind)

| tag | out [NaturalLanguageAudioTag](../NaturalLanguageAudioTag.md) | ... |

Testing

• Added test/ApiMark.DotNet.Fixtures/ByRefParameterClass.cs (with a
  dedicated ByRefTargetClass fixture type, to avoid a substring collision
  with SampleClass in an existing heading-detection test) covering
  out/ref/in parameter methods.
• Added targeted unit tests for TypeNameSimplifier, TypeLinkResolver, and
  DotNetEmitter's signature/display-name builders.
• Full solution test suite passes on net8.0/net9.0/net10.0, all projects
  (including ApiMark.Cpp.Tests and ApiMark.MSBuild.PackageTests).
• End-to-end repro: built a scratch assembly matching the bug report,
  confirmed the pre-fix build reproduces the exact invalid-C#/dead-link
  output, and confirmed the fixed build produces valid C# and working links.
• pwsh ./fix.ps1 and pwsh ./lint.ps1 both run clean.

Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com

[Copilot]

🟡 Changes recommended

The new ByReferenceType unwrapping can cause ref-return methods to render missing the required ref keyword unless return-type handling is updated accordingly.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR fixes documentation rendering for C# ref/out/in parameters by unwrapping Mono.Cecil ByReferenceType in display/link logic and emitting the correct ref-kind keywords in rendered signatures and parameter tables, preventing invalid C# (&) and dead links in generated Markdown.

Changes:

• Unwrap ByReferenceType in TypeNameSimplifier and TypeLinkResolver so displayed type names and link targets don’t include Cecil’s trailing &.
• Emit out/in/ref keywords for byref parameters across signature builders and parameter tables.
• Add fixtures and targeted unit tests covering byref parameter rendering and linkification.

File summaries

File	Description
test/ApiMark.DotNet.Tests/TypeNameSimplifierTests.cs	Adds a unit test ensuring byref types simplify to the element type name (no &).
test/ApiMark.DotNet.Tests/TypeLinkResolverTests.cs	Adds a unit test ensuring byref types linkify to the real page (no & in text/href).
test/ApiMark.DotNet.Tests/DotNetEmitterTests.cs	Adds tests ensuring signatures/display names render out/ref/in keywords and never &.
test/ApiMark.DotNet.Fixtures/ByRefParameterClass.cs	Introduces fixture types/methods for out/ref/in parameter scenarios.
src/ApiMark.DotNet/TypeNameSimplifier.cs	Adds ByReferenceType unwrapping rule to prevent & in simplified names.
src/ApiMark.DotNet/TypeLinkResolver.cs	Adds ByReferenceType unwrapping so links are computed from the element type name.
src/ApiMark.DotNet/DotNetEmitterSingleFile.cs	Prepends ref-kind keyword in parameter type table cells for single-file output.
src/ApiMark.DotNet/DotNetEmitterGradualDisclosure.cs	Prepends ref-kind keyword in parameter type table cells for gradual-disclosure output.
src/ApiMark.DotNet/DotNetEmitter.cs	Adds GetRefKindKeyword and uses it in signature/display-name builders for byref parameters.

Review details

• Files reviewed: 9/9 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟢 Approval recommended

The changes are localized, align with Cecil’s byref model, and are backed by targeted fixture-based unit tests covering the corrected rendering paths.

Review details

• Files reviewed: 9/9 changed files
• Comments generated: 0 new
• Review effort level: Lite