microsoft / microsoft/typespec

C# generator: omit removed types from BinaryData union documentation

Open
#11,342 1 comment 1 reaction 1 assignee Claimed by @live1206 View on GitHub
emitter:client:csharp feature
Dominant language
Java
Stars
5.9k
Forks
394
Avg merge
1d 23h
Merged PRs (30d)
104

Description

## Description

When a `BinaryData` property carries union-item metadata, its generated XML documentation can list a generated type that the provider reference map later removes. The current writer avoids an invalid `cref` by rendering the removed type as `` text, but the resulting documentation may still advertise a type that users cannot access.

## Constraint

`PropertyDescriptionBuilder.CreateBinaryDataExtraDescription` and `GetUnionTypes` run while providers and property descriptions are being built. The provider reference map determines removal only afterward, once all providers and their dependencies have been built and analyzed. Therefore, checking `ProviderReferenceMapAnalyzer.IsRemovedTypeReference` while constructing the description is too early and cannot reliably filter the item.

## Expected fix

Introduce a generic write-time or post-analysis mechanism that omits removed union-item types from generated BinaryData documentation while preserving valid union descriptions. This should not special-case a service or type name, and should retain the current protection against unresolved XML `cref` links in other documentation contexts.

Follow-up from #11288 and review comment https://github.com/microsoft/typespec/pull/11288#discussion_r3626244444.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.