search

dotnet / dotnet-api-docs

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

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

Open gqqnbig opened 5 months ago

gqqnbig commented 5 months ago

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

https://github.com/dotnet/dotnet-api-docs/blob/bc5c3d5ff54f8bea2f49aa32a940111e89bfd574/xml/System.Diagnostics/Debug.xml#L68

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[bot] commented 5 months ago

Tagging subscribers to this area: @tommcdon

colejohnson66 commented 4 months ago

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.