14

When asking around for the conventions of documentation comments in C# code, the answer always leads to using XML comments. Microsoft recommends this approach themselves aswell. https://learn.microsoft.com/en-us/dotnet/csharp/programming-guide/xmldoc/recommended-tags-for-documentation-comments

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

However, when inspecting Microsoft's code, such as ASP.NET Core, comments instead look like this.

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

Does the included doc generation tool work with this convention, or is there a documentation generation tool that uses this convention instead of XML? Why does Microsoft use this convention in their code instead of the XML comments they recommend themselves?

  • 1
    Looks like the inspector is showing it differently, as they are using XML comments in their source code: https://github.com/aspnet/AspNetCore/blob/425c196cba530b161b120a57af8f1dd513b96f67/src/Hosting/Abstractions/src/IWebHostBuilder.cs#L14 – marcusturewicz Feb 03 '19 at 00:24
  • That's odd. It shows this YAML-style of markup when inspecting with both Visual Studio and VSCode. Also, the inspector stills displays the comments properly in popups. Maybe there's some kind of conversion step that takes place. –  Feb 03 '19 at 14:41
  • 1
    Guessing the inspector shows it like that as it's easier to read than XML for humans maybe.. – marcusturewicz Feb 05 '19 at 03:04
  • It looks like [Natural docs](https://www.naturaldocs.org/) which fully supports c#. I don't like xml comments I found them too intrusive. – Jean Gregory Apr 30 '19 at 22:57

1 Answers1

1

Why does Microsoft use this convention in their code instead of the XML comments they recommend themselves?

C# documentation comments provide a precise syntax for encoding many types of content and references, such as to types, parameters, URLs, and other documentation files. It uses XML to accomplish this, and so inherits XML's verbosity. Remember that XML comments go way back to C# version 1, when it was a much more verbose language than it is today.

To avoid the readability problems with XML, Visual Studio displays the comments in a simplified, plain text format. You couldn't run this format back through a compiler. For example, if a comment has the term customerId, it may be ambiguous as to whether it refers to a method parameter or a class field. The ambiguity occurs infrequently enough to not be a problem for a human.

Ideally, there's be a single format that was well-defined for compiler input with good readability that avoids boilerplate. There is an issue open to modernize the comment syntax, but unfortunately, it hasn't gone anywhere in 3 years.

Edward Brey
  • 40,302
  • 20
  • 199
  • 253