Trim the documentation file with the assembly

[SimonCropp]

Where a project writes an XML documentation file, the entries for the types and members the linker removed are now taken out of it. On by default; Squash_TrimDocumentation set to false leaves the file alone.

A source-only package compiled into a library documents its own members into that file, so the file can end up larger than the assembly beside it. Run over copies of Verify's build output:

File	Before	After	Entries removed
Verify.xml net48	817,147	255,533	1,864
Verify.xml net10.0	317,104	228,185	308
Verify.NUnit.xml net48	595,681	17,933	1,919
Verify.NUnit.xml net10.0	100,574	11,059	310

How

• A fifth linker step, RemovedDocumentation, runs after the output is written. It lists the documentation names of everything in the assembly under in/ that is not in the one under out/, reading both with System.Reflection.Metadata.
• The task removes the entries with those names and nothing else. A name spelled differently from the compiler's leaves its entry in place, so a mistake in the spelling cannot remove the entry of a member that is still there.
• What stays is never parsed and written again. The task only leaves bytes out, so the remaining entries are as the compiler wrote them, in the same order.

For a user

• Squash_TrimDocumentation, default true.
• Squash012, a warning when the file is not XML the task can follow. The assembly is trimmed all the same and the file is left as it was.
• Each build writes removed-documentation.txt beside removed.txt, and keeps the compiler's file in the in folder.

Tests

• A new Documented fixture with a member of every shape a documentation name can take. Each summary says Kept. or Removed., and the trimmed file is held to that on all three frameworks.
• The trimmed file is compared with a second, independent way of cutting the same entries out of the compiler's file.
• Integration tests build a real project: the file in bin and in the packed nupkg is trimmed, a repeat build leaves it alone, and turning the setting off compiles again and leaves the compiler's file.

Not covered

• Not run against the .NET 11 linker. The step is placed with +OutputStep:, so it depends on the linker having a step of that name; the canary workflow will show whether it does.
• The version is still 2.0.0.