XML Documentation C# Help

In addition to the C-type comments, illustrated in the preceding section, C# has a very neat feature that we want to highlight: the ability produce documentation in XML. format automatically from special comments. These comments are single-line comments but begin with three slashes instead of the usual two. Within these comments, you can place XML tags containing documentation of the types and type members in your code.

The tags in the following table are recognized by the compiler.

To see how this works, add some XML comments to the MathLibrary. cs file from the “More on Compiling C# Files” section, and call it Math. cs. You will add a <summary> element for the class and for its Add() method, and also a <returns> element and two <par am>elements for the Add() method:

The C# compiler can extract the XML elements from the special comments and use them to generate an XML file. To get the compiler to generate the XML documentation for an assembly, you specify the /doc option when you compile, together with the name of the file you want to be created:

csc /t.library /doc.Math.xml Math.cs

The compiler will throw an error if the XML comments do not result in a well-formed XML document. This will generate an XML file named Math. xml, which looks like this:

Notice how the compiler has actually done some work for you; it has created an <assembly> elem and also added a <member> element for each type or member of a type in the file. Each <member> element has a name attribute with the full name of the member as its value, prefixed by a letter the indicates whether this is a type (T: ), field (F:), or member (M:).

Posted on October 27, 2015 in C# Basics

Share the Story

Back to Top