dotnet / dotnet/docfx

[Bug] `ValueTuple<T1, T2>` is not converted to links when using `"outputFormat": "mref"`

Open
#10,317 0 comments 0 reactions 0 assignees View on GitHub
dotnet
Dominant language
C#
Stars
4.4k
Forks
890
Avg merge
2h 9m
Merged PRs (30d)
11

Description

**Describe the bug**
When using `"outputFormat": "mref"` setting.
`ValueTuple` cref DocComment is not resolved to link.

**To Reproduce**
Steps to reproduce the behavior:

1. Initialize docfx project and configure to include C# source code.
2. Add following property to source code.
```csharp
///
/// -
/// -
/// -
/// -
/// -
/// -
///
public static class DummyClass
{
}
```
3. Run `docfx metadata` command
4. Run `docfx build --serve` command and confirm generated HTML
5. Following cref links are rendered as plain text (`(T1, T2)`).
5.1. ``
5.2. ``

It seems caused by `SymbolDisplay.ToDisplayParts` Roslyn API returns custom `ImmutableArray` that don't contains `href` URL.

**Generated yaml for `ValueTuple`**
```yml
- uid: System.ValueTuple`1
commentId: T:System.ValueTuple`1
isExternal: true
href: https://learn.microsoft.com/dotnet/api/system.valuetuple-1
name: ValueTuple
nameWithType: ValueTuple
fullName: System.ValueTuple
spec.csharp:
- uid: System.ValueTuple`1
name: ValueTuple
isExternal: true
href: https://learn.microsoft.com/dotnet/api/system.valuetuple-1
- name: <
- name: T1
- name: '>'
```

**Generated yaml for `ValueTuple` (href link is missing)**
```yml
- uid: System.ValueTuple`2
commentId: T:System.ValueTuple`2
name: (T1, T2)
nameWithType: (T1, T2)
fullName: (T1, T2)
spec.csharp:
- name: (
- name: T1
- name: ','
- name: " "
- name: T2
- name: )
spec.vb:
- name: (
- name: T1
- name: ','
- name: " "
- name: T2
- name: )
```

**Expected behavior**
`ValueTuple` is rendered as link.

Contributor guide

Open the contributing guide

Research direction

Start by reproducing the issue with `docfx metadata` and `docfx build --serve` using the C# source and cref examples in the report. Trace the `SymbolDisplay.ToDisplayParts` output during cref resolution and compare the generated YAML for `ValueTuple` arities. Done means the two-parameter tuple cref receives an href and renders as a link in the generated HTML.

Written by the indexing model from the issue text.

Assessment

Tech stack
csharp
Domain
documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.