What is the use of XML comments in C#

Question

What is the use of XML comments in C# than signal line and multiple line comments.

i.Single line
Eg:
//This is a Single line comment

ii. Multiple line (/* *         


        

Answer 1

When you create a Dll assambly Xml comments provides the dll's user some information about function or something

Answer 2

From XML Documentation Comments (C# Programming Guide):

When you compile with the /doc option, the compiler will search for all XML tags in the source code and create an XML documentation file.

Also XML comments used by Visual Studio for IntelliSense:

/// <summary>
///  This class performs an important function.
/// </summary>
public class MyClass{}

Will give you nice hints when you are typing code or hovering cursor over member which has xml comments:

NOTE: Usually you should add xml comments only to publicly visible types or members. If member is internal or private, then it's good, but not necessary. There is nice tool GhostDoc (available as extension to Visual Studio) which can generate XML comments from type or member name. It's nice to check if you have good naming - if generated comment is not clear, then you should improve name of member.

I also suggest use simple (non-xml) comments as little, as possible. Because comment is a form of code duplication - it duplicates information which you already have in your code. And here is two problems:

• Your code is not clear enough and you should improve it (renaming, extracting classes or members) instead of adding comments
• When code changes, comments often stay unchanged (programmers are lazy). So when time passes comments become obsolete and confusing.

Good comments should describe why you writing code instead of duplicating what code is doing.

Answer 3

From MSDN:

When you compile with the /doc option, the compiler will search for all XML tags in the source code and create an XML documentation file. To create the final documentation based on the compiler-generated file, you can create a custom tool or use a tool such as Sandcastle.

http://msdn.microsoft.com/en-us/library/b2s063f7.aspx

Answer 4

XML comments, starting with ///, will get picked up by IntelliSense and it will get shown in a pop-up when looking at it from elsewhere. There is a MSDN page explaining how it works.

They will also be picked up by numerous tools that build documentation files, etc.

Answer 5

The XML comments are used to build API documentation which is readable by external tools. IntelliSense also reads these, and uses the contents to show the docs for your code in the assistance tooltips as you type (and in the Documentation window).

The compiler (optionally) extracts all those comments and puts them in a single standalone XML file next to your assembly; this can be parsed.

The idea was to have something like JavaDoc. Unfortunately Microsoft has failed to provide a mainstream mature tool to do so.

Answer 6

Code in all languages usually allows for special comments. These comments can then be parsed by a process which creates automatic documentation of the code. Many libraries are documented this way.

In C# these tools are provided by Microsoft and you use the XML comments to declare that the comment should be picked up by the documentation process - if you have one set up. The comments are also picked up by auto complete.

See also doxygen, JavaDoc for implementations for other languages. See related question Good alternatives to Sandcastle to generate MSDN-style documentation