NDoc User's Guide NDoc 1.3

Tags Supported by NDoc

[This is preliminary documentation and subject to change]

The MSDN and VS.NET documenters that ship with NDoc support all the xml documentation tags defined in the C# Programmer's Reference.

They also support new tags, and extended syntax for some standard tags, as described below.

Some tags may only be used on certain types or members, see the Tag Usage Matrix or individual tag reference pages for further details.

Section Tags

Section tags are used to define the content of the different sections of the documentation of a type or member.

These tags are used as top-level tags.

Tag Description

<event>

[NDoc Only]

An event that may be raised by a member.

<example>

An example of how to use a type or member.

<exception>

An exception that may be thrown by a member.

<exclude/>

[NDoc Only]

Directs the documentation tool to exclude the tagged type or member from the documentation.

The tag overrides all visibility options.

<include>

References an xml node in an include file that contains one or more documentation section tags.

<overloads>

[NDoc Only]

Documentation that applies to all the overloads of a member. It only needs to be specified on the first overload.

The <overloads> tag can have two forms:

  • In the short form, it includes only one or more text blocks that are treated as the summary.
  • In the long form, it can include one or more applicable section tags (summary, remarks and example).

Example:

///<overloads>This method has two overloads.</overloads>
///<summary>This overload just says hello.</summary>
public void SayHello() { ... }
///<summary>This one says hello to someone.</summary>
public void SayHello(string toSomeone) { ... }

<param>

A member parameter.

<permission>

Security permissions required to access a member.

<preliminary>

[NDoc Only]

Marks the documentation of a type or member as preliminary. This tag can include block tags like <para> in order to put a custom warning into your help topics about preliminary items.

If the tag is empty, preliminary topics will include the default message:

[This is preliminary documentation and subject to change.]

It is also possible to mark an entire help project as preliminary using the Preliminary project setting.

<remarks>

Additional information about a type or member, supplementing the description in <summary>.

<returns>

A member's return value.

<seealso>

Adds a link to the See Also section.

Do not include this tag in the <remarks> section.

Alternate syntax:

  • <seealso href="url">[label]</seealso>
  • <seealso cref="member">[label]</seealso>

<summary>

A short description of a type or member.

<threadsafety>

[NDoc Only]

Denotes how a class or structure behaves in multi-threaded scenarios.

This tag has 2 attributes static and instance that can be set to true or false. The default behavior is that static members are thread safe and instance members may not be.

Textual content can be included as the inner text of this tag in order to provide additional information about the thread safety of the type.

/// <summary>This overload just says hello.</summary>
/// <threadsafety static="true" instance="true">
///    <para>More information about using this class across thread</para>
/// </threadsafety>
public class SafeClass() { ... }

<value>

Defines a property value.

Block Tags

Block tags format text within the top-level tags. They are typically used to add structure to the text inside <remarks> and <example> sections .

Tag Description

<code>

A block of code.

<list>

A definition list or table.

<note>

[NDoc Only]

A formatted note block.

Example:

/// <summary>
/// <note>This is a note in the summary.</note>
/// </summary>
public class SomeClass() { ... }

gives,

Note This is a note in the summary.

<para>

Delimits a text paragraph.

Inline Tags

Inline tags are typically used inside <para> blocks.

Tag Description

<c>

Marks inline code.

<paramref>

A reference to a parameter.

<see>

An Inline reference to another member or type.

Alternate syntax:

  • <see href="url">[label]</see>
  • <see cref="member">[label]</see>
  • <see langword="xxx"/>
    where xxx is null, sealed, static, abstract or virtual