Class description of `System.Diagnostics.Debug` is different between online and XML doc

[gqqnbig]

The class description of System.Diagnostics.Debug online is "Provides a set of methods and properties that help debug your code."

dotnet-api-docs/xml/System.Diagnostics/Debug.xml

Line 68 in bc5c3d5

<summary>Provides a set of methods and properties that help debug your code.</summary>

But the class description of System.Diagnostics.Debug from actual source code is "Provides a set of properties and methods for debugging code."

https://github.com/dotnet/runtime/blob/2d7eea252964e69be94cb9c847b371b23e4dd470/src/libraries/System.Private.CoreLib/src/System/Diagnostics/Debug.cs#L15-L17

Coming with a Java background, I was always under the impression that the API reference (MSDN) is generated from XML documentation from the actual source code, plus extra long examples and remarks.

I'm all in favor of extra remarks, usages, and code examples that do not fit in Visual Studio tooltip, but why does the one sentence description of System.Diagnostics.Debug differ?

Can anyone educate me on the workflow or the advantage in doing so?

Also would you like to update the summary element in https://github.com/dotnet/dotnet-api-docs/blob/bc5c3d5ff54f8bea2f49aa32a940111e89bfd574/xml/System.Diagnostics/Debug.xml and match the actual source code, and cause less confusion?

[dotnet-policy-service]

Tagging subscribers to this area: @tommcdon

[colejohnson66]

In normal usage, the API documents are generated from the source code; Adding <GenerateDocumentationFile>True</GenerateDocumentationFile> to your csproj will cause the compiler to output the XML file with the DLL, EXE, etc.

However, the runtime and friends have a weird history where documentation was extracted out of the source repository into here. The documentation you see on the site is, essentially, a modified version of what is in the source. In a perfect world, this would allow documentation writers and code authors to be different people and not have merge conflicts, but that doesn't work in practice. There's an open issue (dotnet/runtime#44969) to backport this repository back into the source code, but little progress has been made.