15

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?

Improve this question
4
  • 1
    Looks like the inspector is showing it differently, as they are using XML comments in their source code: github.com/aspnet/AspNetCore/blob/… Commented Feb 3, 2019 at 0: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. Commented Feb 3, 2019 at 14:41
  • 1
    Guessing the inspector shows it like that as it's easier to read than XML for humans maybe.. Commented Feb 5, 2019 at 3:04
  • It looks like Natural docs which fully supports c#. I don't like xml comments I found them too intrusive. Commented Apr 30, 2019 at 22:57

1 Answer 1

Reset to default
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.

Improve this answer
Sign up to request clarification or add additional context in comments.

2 Comments

curious if there is an extension to bring this functionality to VSCode?
update——seems what i was looking for is here: marketplace.visualstudio.com/…

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.