documentation guidelines

F#/C#/C++

A documentation comment comes immediately before a type or member declaration, and starts with three slashes:

/// <summary>Cancels a running query.</summary>
public void Cancel() { ... }

Multiline comments can be done either like this:

/// <summary>
/// Cancels a running query
/// </summary>
public void Cancel() { ... }

or like this (notice the extra star at the start):

/**
 <summary> Cancels a running query. </summary>
*/
public void Cancel() { ... }

If you compile with the /doc directive, the compiler extracts and collates documentation comments into a single XML file. In case of C++, compiler processes the documentation tags into .xdc file for each compiland, and xdcmake.exe will process the .xdc files to an .xml file. Final XML file has two main uses:

• If placed in the same folder as the compiled assembly, Visual Studio automatically reads the XML file and uses the information to provide IntelliSense member listings to consumers of the assembly of the same name.

• Third-party tools (such as Sandcastle and NDoc) can transform XML file into an HTML help file.

Standard Documentation Tags

Here are the standard XML tags that Visual Studio and documentation generators recognize.

Important remark: Tags denoted as Obligatory are required to appear in the code.

• <summary> Obligatory

<summary>...</summary>

Indicates the tool tip that IntelliSense should display for the type or member; typically a single phrase or sentence.

• <remarks>

<remarks>...</remarks>

Additional text that describes the type or member. Documentation generators pick this up and merge it into the bulk of a type or member’s description.

• <param> Obligatory (if applicable)

<param name="name">...</param>

Explains a parameter on a method.

• <returns> Obligatory (if applicable)

<returns>...</returns>

Explains the return value for a method.

• <exception> Obligatory (if applicable)

<exception [cref="type"]>...</exception>

Lists an exception that a method may throw (cref refers to the exception type).

• <example>

<example>...</example>

Denotes an example (used by documentation generators). This usually contains both description text and source code (source code is typically within a <c> or <code> tag).

• <c>

<c>...</c>

Indicates an inline code snippet. This tag is usually used inside an block.

• <code>

<code>...</code>

Indicates a multiline code sample. This tag is usually used inside an <example> block.

• <see>

<see cref="member">...</see>

Inserts an inline cross-reference to another type or member. HTML documentation generators typically convert this to a hyperlink. The compiler emits a warning if the type or member name is invalid. To refer to generic types, use curly braces; for example, cref="Foo{T,U}".

• <list>

<list type=[ bullet | number | table ]>
 <listheader>
 <term>...</term>
 <description>...</description>
 </listheader>
 <item>
 <term>...</term>
 <description>...</description>
 </item>
</list>

Instructs documentation generators to emit a bulleted, numbered, or table-style list.

(special thanks to Sand3r for creating majority of this text)

Angular2

(work in progress)

In case of the frontend code, an utility called TypeDoc can be used. It supports following javadoc tags:

• @param <param name>
• @return(s)

Exemplary code with documentation:

/**
 * Description of the function
 * @param value  Comment for parameter ´value´.
 * @returns      Comment for special return value.
 */
function foo(value:number):number;

For now, more information can be found here.