microsoft / microsoft/typespec
[http-client-csharp] Do not include internal union variant types in the generated property description
- Dominant language
- Java
- Stars
- 5.9k
- Forks
- 394
- Avg merge
- 1d 23h
- Merged PRs (30d)
- 104
Description
## Describe the bug
For a property backed by a TypeSpec union, the C# emitter generates a `BinaryData` property with a "Supported types" list in the XML docs, built from the union item types. That list includes **internal** variant types, which is not useful to a consumer: they cannot name or construct the type being suggested.
`PropertyDescriptionBuilder.GetUnionTypesDescriptions` emits a cref for every union item with no accessibility filter:
```csharp
description = new XmlDocStatement("description", [$"{item:C}"]);
```
and `CodeWriter.AppendTypeForCRef` only falls back to plain text when the type was removed from the output (`ProviderReferenceMapAnalyzer.IsRemovedTypeReference`), not when it is internal.
The result compiles — an in-assembly cref to an internal type is legal — but it documents an API surface the caller cannot reach.
## Example
In `Azure.AI.Projects.Agents`, `DeclarativeAgentDefinition.ToolChoice` is a public `BinaryData` property whose union variants are all `internal`:
```csharp
///
/// Supported types:
///
///
/// .
///
///
/// .
///
///
///
public BinaryData ToolChoice { get; set; }
```
`InternalToolChoiceParam` is `internal abstract`, so a consumer cannot construct one to assign to `ToolChoice`.
## Expected behavior
Internal union variant types should be omitted from the generated "Supported types" list. If every variant is internal, the list should be omitted entirely rather than emitted empty, while the surrounding `BinaryData` guidance (`FromObjectAsJson` / `FromString` and the examples) is preserved.
## Reproduction
Not playground-reproducible; this is emitter output behavior. It reproduces on any library with a public `BinaryData` union property whose variants are internal, for example a spec with `@access(Access.internal)` on the union variant models. A concrete instance is `sdk/ai/Azure.AI.Projects.Agents/src/Generated/Models/DeclarativeAgentDefinition.cs` in Azure/azure-sdk-for-net#62649.
Note this is independent of API compatibility processing — it is not specific to regenerated libraries with a last contract.
## Related
- #11839 — where this was raised in review
- #11842 — the related question of whether internal union variants should be kept in the output at all
Contributor guide
Research direction
Search for PropertyDescriptionBuilder.GetUnionTypesDescriptions and read how it builds union item descriptions, then inspect CodeWriter.AppendTypeForCRef and the accessibility information available for referenced types. Verify the generated XML docs for DeclarativeAgentDefinition.ToolChoice: internal variants are absent, the list is omitted when none are public, and the surrounding BinaryData guidance remains.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- csharp
- Domain
- tooling
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 72/100