Skip to content

Incorrect <inheritdoc cref="..."> value when the underlying type is generic #907

@aradalvand

Description

@aradalvand

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:

  1. 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.
  2. Declare a custom generic type that implements an interface like IParseable — say Ratio<T>
  3. Finally, declare a Vogen value object type where the underlying type is the generic type you just defined: [ValueObject<Ratio<int>>]
  4. 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}.)

Image

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions