Preserve xml comments when re-generating the suppression file

[ViktorHofer]

Today, when a suppression file already exists and is regenerated via the --generate-suppression-file or /p:GenerateSuppressionFile=true flag, xml comments applied to elements are lost. In dotnet/runtime we have comments encoded in suppression files to explain why certain suppressions are necessary.

We should explore if we can change the XmlSerializer currently used to preserve xml comments. Alternatively we could discuss if we want to support an additional output format like JSON. That would have the advantage of in-built code comment support when using a library like System.Text.Json, and the availability of a source generator which remove the dependency on reflection during serialization/deserialization.

[ghost]

@dotnet/area-infrastructure-libraries a new issue has been filed in the ApiCompat area, please triage

[jpobst]

Another option would be to add a new element to <Suppression> like <Justification> that would not be consumed by ApiCompat, but would be deserialized and serialized.

Instead of:

<!-- Exposed publicly only in implementation for serialization compat. -->
<Suppression>
  <DiagnosticId>CP0001</DiagnosticId>
  <Target>T:System.IO.Compression.ZLibException</Target>
</Suppression>

It would be this:

<Suppression>
  <DiagnosticId>CP0001</DiagnosticId>
  <Target>T:System.IO.Compression.ZLibException</Target>
  <Justification>Exposed publicly only in implementation for serialization compat.</Justification>
</Suppression>