Recreate bad xml-files with clean content

[Tasteful]

I have the same issue as you with the bad format of netstandard.xml that I have seen you report in the dotnet repo and this is a way to get most of the documentation comments to work also for this bad file. This is a hack to get around from the original problem and is nothing that you need to include, I'm maintain an inhouse version where this fix is included but want to share that with you in case you think it's an idea to include it in the original version.

This PR contains a method that only will be executed if we run into an xml-parser error and in that case we read the xml-file, line by line and finding all the correct xml-member-elements and adding them into a temporary file. During next run we use the temporary file instead of the original file to get faster speed in the parsing and not always need to read the xml-file line-by-line.

The temporary file name is build from the sha1 hash of the original file content.

[saucecontrol]

Howdy! Thanks for sharing your fix. I like your approach, but I think I'll wait a little longer for a response from Microsoft to see if they'll fix the issue on their end before taking this. It's such a specific issue to have to code a workaround for.

Theirs are the only packages I've seen with bad XML like that, and as far as I know they've fixed the tooling issue that caused the problem. I saw reports of a few other packages with bad docs, but I think they've pushed updates to all of them except NETStandard at this point.

[saucecontrol]

I came up with an alternate workaround for the bad NETStandard 2.0 docs that doesn't require any code changes and still allows for automated builds to work.

<PropertyGroup Condition="'$(TargetFramework)'=='netstandard2.0'">
    <NoWarn>$(NoWarn);IDT001</NoWarn>
</PropertyGroup>

<ItemGroup Condition="'$(TargetFramework)'=='netstandard2.0'">
    <PackageDownload Include="NETStandard.Library.Ref" Version="[2.1.0]" />
    <InheritDocReference Include="$([MSBuild]::EnsureTrailingSlash('$(NugetPackageRoot)'))netstandard.library.ref\2.1.0\ref\netstandard2.1\netstandard.xml" />
</ItemGroup>

PackageDownload ensures the package is in the local NuGet cache without actually adding a dependency, and then we can pick up the corrected/updated netstandard.xml from there for InheritDoc to use.

[Tasteful]

Nice, i will try to use that one. I can say directly that I got no errors :)

[Tasteful]

Maybe if the RefAssemblyPaths="@(_ResolveAssemblyReferenceResolvedFiles)" on the task is changed to a private variable we probably can filter out the netstandard2.0 reference from that one and the IDT001 warning can still be enabled.

[saucecontrol]

Yeah, a private copy of that variable would be a good idea. You wouldn't be able to remove the netstandard2.0 reference because that would break the base type/member resolution, but we might be able to substitute it for netstandard2.1.

I was just playing around with https://github.com/tunnelvisionlabs/ReferenceAssemblyAnnotator and found it breaks InheritDoc because it rewrites some of the assembly references to its new annotated copies. I'll have to add a target that steps in earlier in the process to capture the ref locations anyway.

[saucecontrol]

Since Microsoft declined to fix their bad XML (https://github.com/dotnet/standard/issues/1527#issuecomment-1244413631) and since the NETStandard ref package had the only bad XML file I've seen left in the wild, I decided to just ship a replacement with the package in https://github.com/saucecontrol/InheritDoc/commit/de3a856617fcbb71ab1adc66ab36d43151c19435

Thanks again for your effort on this, but hopefully it's not necessary anymore 🤞