Visual Studio XML Comment Tags - VirtualPhotonics/Vts.MonteCarlo GitHub Wiki

All public classes, methods and properties must be documented. In Visual Studio, when you type '///' on the line above the class, method, property or field, a summary tag will be automatically created and if there are any parameters, it will generate an outline for these also. See the examples below.

Class example

/// <summary>
/// Class that contains really useful methods for doing exactly what you want to do.
/// </summary>
public class ReallyUsefulClass

Method example

/// <summary>
/// Method to perform a very important task
/// </summary>
/// <param name="FirstParameter">the first parameter representing an important value</param>
/// <param name="SecondParameter">the second parameter also representing an important value</param>
/// <returns>void</returns>
public void PerformImportantTask(int FirstParameter, double SecondParameter)

Property example

/// <summary>
/// Specifies if any of the settings have changed
/// </summary>
/// <value>The SettingsChanged property gets/sets the _settingsChanged data member.</value>
public bool SettingsChanged { get { return _settingsChanged; } set { _settingsChanged = value; } }

Recognized Tags

The summary tag is the most important but below you will find a description of all tags and what they are used for.
This is the Microsoft description of the tags: http://msdn.microsoft.com/en-us/library/5ast78ax(v=VS.100).aspx.

summary

This is the main tag for all documentation.
Example:

/// <summary>
/// Class that contains really useful methods for doing exactly what you want to do.
/// </summary>

remarks

The remarks tag is similar to the summary tag and should be used to make special notes about the item being documented.
Example from the code:

/// <remarks>Warning - Setting this value also modifies Mus!</remarks>

example, code, c

These tags are for showing how to use the item by combining descriptions and code

/// <example>
/// <c>The c tag is like the code tag but is used for just one line of code</c>
/// The example tag is where you mark the start of an example showing how to use the item - it can stand on it's own or be nested in the summary
/// <code>
/// // the code tag defines a section of of text as code and is often used within the example tag like this
/// PerformImportantTask(myInteger, myDouble); 
/// </code>
/// </example>

para

The para tag is to define a new paragraph and has to be used within other comment tags (summary, remarks or example)
Example:

/// <summary> 
/// <para>The para tag creates a new paragraph within a summary or remarks</para>
/// </summary>

value

The value tag lets you describe the value that a property represents.
Example:

/// <summary>
/// The Name property represents the employee's name
/// </summary>
/// <value>The Name property gets/sets the _name data member.</value>
public string Name { get { return _name; } set { _name = value; } }

param, typeparam

These tags are inserted automatically when you type '///' above the item being documented and will match the parameters in the code. They are not updated if the code changes so once they have been created, they must be updated manually. See paramref and typeparamref for examples.

paramref, typeparamref

The paramref and the typeparamref tags indicate that a word in the comments is a parameter.
Example of param and paramref:

/// <summary>
/// The parameter <paramref name="FirstParameter"/> takes an integer
/// </summary>
/// <param name="FirstParam">The first parameter that is defined</param>
public void myMethod(int FirstParameter)

Example of typeparam and typeparamref:

/// <summary>
/// Creates a new array of arbitrary type <typeparamref name="T"/>
/// </summary>
/// <typeparam name="T">The element type of the array</typeparam>
public static T[] mkArray<T>(int n)
{
    return new T[n];
}

exception

The exception tag references an exception that is available in the current compilation environment.
Example:

/// <exception cref="System.Exception">This error is thrown when...</exception>

list, listheader, item, term, description

These tags are used to create lists (bullet, number or table) within other comment tags (summary, remarks or example)
Example:

/// <summary>
/// <list type="table">
/// <listheader>
/// <term>term</term>
/// <description>description</description>
/// </listheader>
/// <item>
/// <term>term</term>
/// <description>description</description>
/// </item>
/// </list>
/// </summary>

include

The include tag allows parts of an external XML document to be included in the comments. The attributes are file, which is the file to be included, path, which is the XPath statement to the comments to include.
Example:

/// <include file='/XML/External/Documentation.XML' path='doc/members/member[@name="M:PopulateClassList"]'/>

permission

The permission tag lets you document the access of a member. This given code element cref must exist.
Example:

/// <permission cref="System.Security.PermissionSet">Everybody can access this method</permission>

see, seealso

The see tag lets you specify a link from within the text. The seealso specifies text to appear in a See Also section.
Examples:

/// <see cref="System.Console.WriteLine(System.String)"/>
/// <seealso cref="TestClass.Main"/>

Special Characters

The comments are formatted in XML so there are certain characters that cannot be used directly, like the angled brackets. see the list below for the special characters and how to insert them.
< use <
> use >
& use &
' use ' (only need this if you are nesting text inside text that is already surrounded by single quotes)
" use " (only need this if you are nesting text inside text that is already surrounded by quotes)