-
Notifications
You must be signed in to change notification settings - Fork 88
Incorrect <inheritdoc cref="..."> value when the underlying type is generic #907
Copy link
Copy link
Open
Description
Here's a minimal repro: https://github.comaradalvand/vogen-warning-repro
Steps to reproduce:
- You can just clone the repo linked above and then run
dotnet build.
Alternatively, these are the individual steps:
- Add
<GenerateDocumentationFile>true</GenerateDocumentationFile>to your MSBuild configuration (e.g. `.csproj file), which incidentally enables a subset of compiler warnings related to problematic XML documentation usage. - Declare a custom generic type that implements an interface like
IParseable— sayRatio<T> - Finally, declare a Vogen value object type where the underlying type is the generic type you just defined:
[ValueObject<Ratio<int>>] - Build the project
The following warnings will be emitted from the Vogen-generated code:
vogen-warning-repro net10.0 succeeded with 8 warning(s) (1.9s) → bin/Debug/net10.0/vogen-warning-repro.dll
/home/arad/scratchpad/vogen-warning-repro/obj/Debug/net10.0/Vogen/Vogen.ValueObjectGenerator/_ImageAspectRatio.g.cs(172,29): warning CS1584: XML comment has syntactically incorrect cref attribute 'Ratio{int}.TryParse(System.ReadOnlySpan{char}, System.IFormatProvider? , out Ratio{int})'
/home/arad/scratchpad/vogen-warning-repro/obj/Debug/net10.0/Vogen/Vogen.ValueObjectGenerator/_ImageAspectRatio.g.cs(172,35): warning CS1658: Type parameter declaration must be an identifier not a type. See also error CS0081.
/home/arad/scratchpad/vogen-warning-repro/obj/Debug/net10.0/Vogen/Vogen.ValueObjectGenerator/_ImageAspectRatio.g.cs(194,29): warning CS1584: XML comment has syntactically incorrect cref attribute 'Ratio{int}.TryParse(string? , System.IFormatProvider? , out Ratio{int})'
/home/arad/scratchpad/vogen-warning-repro/obj/Debug/net10.0/Vogen/Vogen.ValueObjectGenerator/_ImageAspectRatio.g.cs(194,35): warning CS1658: Type parameter declaration must be an identifier not a type. See also error CS0081.
/home/arad/scratchpad/vogen-warning-repro/obj/Debug/net10.0/Vogen/Vogen.ValueObjectGenerator/_ImageAspectRatio.g.cs(216,29): warning CS1584: XML comment has syntactically incorrect cref attribute 'Ratio{int}.Parse(System.ReadOnlySpan{char}, System.IFormatProvider? )'
/home/arad/scratchpad/vogen-warning-repro/obj/Debug/net10.0/Vogen/Vogen.ValueObjectGenerator/_ImageAspectRatio.g.cs(216,35): warning CS1658: Type parameter declaration must be an identifier not a type. See also error CS0081.
/home/arad/scratchpad/vogen-warning-repro/obj/Debug/net10.0/Vogen/Vogen.ValueObjectGenerator/_ImageAspectRatio.g.cs(229,29): warning CS1584: XML comment has syntactically incorrect cref attribute 'Ratio{int}.Parse(string, System.IFormatProvider? )'
/home/arad/scratchpad/vogen-warning-repro/obj/Debug/net10.0/Vogen/Vogen.ValueObjectGenerator/_ImageAspectRatio.g.cs(229,35): warning CS1658: Type parameter declaration must be an identifier not a type. See also error CS0081.
The warning is complaining about <inheritdoc> elements that look like this:
/// <inheritdoc cref="Ratio{int}.TryParse(System.ReadOnlySpan{char}, System.IFormatProvider? , out Ratio{int})"/>This is apparently not correct; type parameters of the target symbol cannot be replaced with type arguments. This means that the correct cref value is:
/// <inheritdoc cref="Ratio{T}.TryParse(System.ReadOnlySpan{char}, System.IFormatProvider? , out Ratio{T})"/>(Notice the change from Ratio{int} to Ratio{T}.)

Reactions are currently unavailable
Metadata
Metadata
Assignees
Labels
No labels