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:
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:
/// <remarks>
/// Supported types:
/// <list type="bullet">
/// <item>
/// <description> <see cref="string"/>. </description>
/// </item>
/// <item>
/// <description> <see cref="InternalToolChoiceParam"/>. </description>
/// </item>
/// </list>
/// </remarks>
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
Describe the bug
For a property backed by a TypeSpec union, the C# emitter generates a
BinaryDataproperty 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.GetUnionTypesDescriptionsemits a cref for every union item with no accessibility filter:and
CodeWriter.AppendTypeForCRefonly 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.ToolChoiceis a publicBinaryDataproperty whose union variants are allinternal:InternalToolChoiceParamisinternal abstract, so a consumer cannot construct one to assign toToolChoice.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
BinaryDataguidance (FromObjectAsJson/FromStringand the examples) is preserved.Reproduction
Not playground-reproducible; this is emitter output behavior. It reproduces on any library with a public
BinaryDataunion property whose variants are internal, for example a spec with@access(Access.internal)on the union variant models. A concrete instance issdk/ai/Azure.AI.Projects.Agents/src/Generated/Models/DeclarativeAgentDefinition.csin 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