search

dotnet / dotnet-api-docs

.NET API reference documentation (.NET 5+, .NET Core, .NET Framework)
https://docs.microsoft.com/dotnet/api/
Other
718 stars 1.56k forks source link

Value on DocId's MemberSignature tag does not match with corefx's member name when referring an innner class of a generic-type class. #2854

Open jozkee opened 5 years ago

jozkee commented 5 years ago

The name of members in xml files in corefx/artifacts/bin folder, generated from triple-slash comments within the source code does not match the dotnet-api-docs/xml <MemberSignature Language="DocId">'s value when it references an inner class within a generic class.

Take the following signature as an example:

public static ImmutableArray<TSource> ToImmutableArray<TSource>(this ImmutableArray<TSource>.Builder builder)

This signature recieves a param of the type ImmutableArray<TSource>.Builder, which is a class defined within the ImmutableArray<TSource> class. This signature is converted to the following values.

on corefx\artifacts\bin\System.Collections.Immutable\netcoreapp-Debug\System.Collections.Immutable.xml:

<member name="M:System.Collections.Immutable.ImmutableArray.ToImmutableArray``1(System.Collections.Immutable.ImmutableArray{``0}.Builder)">

on dotnet-api-docs\xml\System.Collections.Immutable\ImmutableArray.xml:

<MemberSignature Language="DocId" Value="M:System.Collections.Immutable.ImmutableArray.ToImmutableArray``1(System.Collections.Immutable.ImmutableArray`1.Builder{``0})" />

As you can see, there is a difference in the Value of both nodes property, right in the parameter type.

This is affecting us because we were automatically porting APIs documented via triple-slash comments to the docs repo, with this difference we are unable to match the APIs and we need to go and manually copy-paste the info in the source to the docs repo.

In addition, in the docs page you can see that the name of the overload says that it expects a ImmutableArray<TSource> when it should say ImmutableArray<TSource>.Builder.

mairaw commented 5 years ago

Thanks @Jozkee! @joelmartinez can you investigate and transfer this issue to the appropriate Azure DevOps repo? Making sure we're using the right DocID also impacts the IntelliSense output.

joelmartinez commented 5 years ago

Great find @Jozkee ... ok @mairaw, I've created a corresponding bug in devops.

mairaw commented 5 years ago

Thanks @joelmartinez!

TianqiZhang commented 4 years ago

For the overload name in the doc page, it's a separated bug in ECMA2Yaml, not related to the DocId issue. I've opened CEAPEX bug 165060 to track it. @mairaw @joelmartinez

TianqiZhang commented 4 years ago

@mairaw @joelmartinez overload name fix is released, I triggered master build and here's result: image @mairaw you can re-publish live branch to fix it in live page.

mairaw commented 4 years ago

Build kicked off @TianqiZhang