microsoft / microsoft/typespec

Feature request: C# generator should format generated methods as XML doc cref elements

Open
#11,202 1 comment 1 reaction 0 assignees View on GitHub
emitter:client:csharp feature
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.