Альтернатива XML-комментариям к документации в C#

Question

Когда вы спрашиваете об условных комментариях к документации в коде C#, ответ всегда приводит к использованию XML-комментариев. Microsoft рекомендует такой подход и самим. https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/xmldoc/recommended-tags-for-documentation-comments

/// <summary>
/// This is an XML comment.
/// </summary>
void Foo();

Однако при проверке кода Microsoft, такого как ASP.NET Core, комментарии выглядят следующим образом.

//
// Summary:
//     A builder for Microsoft.AspNetCore.Hosting.IWebHost.
public interface IWebHostBuilder

Работает ли включенный инструмент создания документов с этим соглашением, или есть инструмент создания документации, который использует это соглашение вместо XML? Почему Microsoft использует это соглашение в своем коде вместо комментариев XML, которые они сами рекомендуют?

Answer 1

Почему Microsoft использует это соглашение в своем коде вместо XML-комментариев, которые они сами рекомендуют?

Комментарии к документации C# предоставляют точный синтаксис для кодирования многих типов содержимого и ссылок, таких как типы, параметры, URL-адреса и другие файлы документации. Для этого он использует XML и, таким образом, наследует многословие XML. Помните, что XML-комментарии восходят к C# версии 1, когда это был гораздо более многословный язык, чем сегодня.

Чтобы избежать проблем с удобочитаемостью XML, Visual Studio отображает комментарии в упрощенном текстовом формате. Вы не могли запустить этот формат обратно через компилятор. Например, если в комментарии есть терминcustomerId, может быть неясно, относится ли оно к параметру метода или к полю класса. Неоднозначность возникает достаточно редко, чтобы не быть проблемой для человека.

В идеале должен быть единый формат, четко определенный для входных данных компилятора, с хорошей читабельностью и отсутствием шаблонов. Открыта проблема с модернизацией синтаксиса комментариев, но, к сожалению, за 3 года она никуда не исчезла.