microsoft / microsoft/typespec
Feature request: C# generator should format generated methods as XML doc cref elements
- Dominant language
- Java
- Stars
- 5.9k
- Forks
- 394
- Avg merge
- 1d 23h
- Merged PRs (30d)
- 104
Description
## Feature request
Please add support for formatting generated C# method references as XML documentation cref elements.
### Scenario
The Azure SDK management generator needs to emit documentation that points from an extension method to the mockable method users should mock instead:
```xml
To mock this method, please mock instead.
```
For methods with generic parameter types, the cref must use XML-doc generic syntax, for example:
```xml
```
### Current behavior
I validated the existing C# generator `:C` formatter in two ways:
1. Formatting individual `CSharpType` values with `:C` and composing them inside `cref="..."` does not work because `:C` emits complete XML doc tags/prose, such as `` or ` where T is of type `.
2. Formatting `MethodSignature` directly with `:C`, for example `$"To mock this method, please mock {targetSignature:C} instead."`, compiles but emits ``, referencing the `MethodSignature` type rather than the represented generated method.
`CSharpType` also does not appear to expose an XML-doc cref string conversion API. `ToString()` emits C# syntax such as `global::System.Collections.Generic.IEnumerable`, not XML-doc cref syntax such as `IEnumerable{string}`.
### Requested API/behavior
Please consider supporting `:C` on a generated C# method representation, such as `MethodSignature` or `MethodProvider`, to emit a complete cref element for the represented generated method, including the declaring type and parameter type list.
If the declaring type cannot be inferred from `MethodSignature`, a helper/API that accepts the declaring `CSharpType` plus the method signature would also work.
This would let generators rely on base C# generator XML-doc formatting instead of manually building cref strings and generic type parameter syntax.
Context: Azure SDK issue https://github.com/Azure/azure-sdk-for-net/issues/60758
Contributor guide
Research direction
Start by tracing the existing C# generator `:C` formatter and the `MethodSignature` and `MethodProvider` representations. Compare their output with the requested complete XML documentation `cref` element, including declaring type and generic parameter syntax; done means generated method references produce the requested XML-doc form without manual string construction.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- csharp
- Domain
- tooling
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100