XML Comment tags supported by GhostDoc

GhostDoc Pro supports help documentation generation for all tags recommended by Microsoft - Recommended Tags for Documentation Comments 

This article covers the XML Comment tags that are supported by GhostDoc when generating help documentation. You are welcome to modify your GhostDoc templates to product XML Comments that include tags like author, todo, etc and these will be included with your source code XML Comments but not the help docs.

The summary tag is the most basic of tags. The list below is the complete set currently supported by GhostDoc.

 

Sections

Sections are used to define the content for the different sections of the documentation of a type or member and are always top-level tags that appear at the root of the XML comments block. Examples are summary and remarks.

summary

The summary tag is used to provide a brief description of the type or member. The description will appear in IntelliSense and the Object Browser. As such, it should be kept brief. Use the remarks tag to provide more detailed information about the type or member.

Syntax:

<summary>description</summary>

remarks

The remarks tag is used to provide a more detailed information about the type or member such as how it is used, its processing, etc. Remarks will only appear in the help file and can be as long as necessary.

Syntax:

<remarks>description</remarks>

example

The example tag is used to define an example for a type or one of its members to show how it is used. One or more code tags are typically included to show the example code.

Syntax:

<example>
Optional code description

<code language="cs">
/// Example code
</code>

</example>

seealso

The seealso tag is used to create a link to another API topic or an external website within the See Also section of a topic.

Syntax:

<seealso cref="member" />

or

<seealso cref="member">inner text</seealso>

param

The param tag is used to describe method parameters. There should be one param tag for each method or operator overload parameter. The description will be used as the display text for the parameter in IntelliSense and the Object Browser.

Syntax:

<param name="paramName">Parameter description</param>

typeparam

The typeparam tag is used to describe generic parameters on generic types and methods. There should be one typeparam tag for each generic type parameter in the class or method declaration. The description will be used as the display text for the parameter in IntelliSense and the Object Browser.

Syntax:

<typeparam name="typeParamName">Type parameter description</typeparam>

returns

The returns tag is used to describe the return value of a method. The description will appear in the Object Browser.

Syntax:

<returns>description</returns>

value

The value tag is used to provide a more detailed description of a property value. Use it when necessary to provide more detailed information about a property's value such as how it is used, valid values, etc.

Syntax:

<value>description</value>

exception

The exception tag is used to list exceptions that can be thrown by a type's member. exceptionType is the name of the exception type that can be thrown.

Syntax:

<exception cref="exceptionType">description</exception>

permission

The permission tag is used to list define the permissions required to access a type or member. The cref attribute is used to specify a permission type required to access the type or member. It is typically one of the .NET permission set types such as PermissionSet or SecurityPermission. Use the inner text to describe how the permission applies to the type or member.

Syntax:

<permission cref="permissionTypeOrMember">inner text</permission>

Blocks

Blocks format text within the top-level section tags. They are typically used to add structure to the text inside those tags. Examples are code and list.

code

The code tag is used to indicate that a multi-line section of text should be formatted as a code block. Use code to mark a multi-line block of lines as code. Use the c tag to mark inline text as code.

Syntax:

<code language="languageId"
	[title="Optional title"]>

/// Code to display

</code>

Here is the list of language attribute values:

Language ID (case-insensitive)Language Syntax
CS, C#, CSharpC#
VB, vbnet, VB.NETVB/VB.NET
cpp, C++C++
js, jscript, JavaScriptJavaScript
htm, html, xml, xslXML/HTML
XAMLXAML
sqlSQL
Anything else (i.e. "none")o language, no special formatting

For documentation on how to use the code tag, please see Including code samples within XML Comments

list

The list block describes content that should be displayed as a list or a table.

Syntax:

<list type="bullet">
	<item>
		<term>Optional term</term>
		<description>Required description.  If term is omitted, the description can be listed as the item tag's inner text.</description>
	</item>
	...
</list>

or

<list type="number" [start="###"]>
	<item>
		<term>Optional term</term>
		<description>Required description.  If term is omitted, the description can be listed as the item tag's inner text.</description>
	</item>
	...
</list>

or

<list type="definition">
	<item>
		<term>Required term</term>
		<description>Required description</description>
	</item>
	...
</list>

or

<list type="table">
	<listheader>
		<term>Multi-column table header</term>
		<term>Add additional term or description tags to create new header columns</term>
		...
	</listheader>
	<item>
		<description>Multi-column table</description>
		<description>Add additional term or description tags to create new columns</description>
		...
	</item>
	...
</list>

para

The para block is used to start a new paragraph within other tags. As an alternative, you can use the HTML <p /> or <p> </p> tags to create paragraphs. Making the tag self-closing or empty will cause the tag to be ignored unless it creates an initial paragraph break.

Syntax:

<para>paragraph content</para>

note

The note block is used to create a note-like section within a topic to draw attention to some important information.

Syntax:

<note type="noteType">note content</note>

The type attribute defines the note type. The noteType value should be one of the values shown below. If omitted, a default note type of "note" is assumed. The note content can be any valid inline or block XML comments similar to the remarks tag.

Important: The type attribute value is case-sensitive. Unrecognized values will default to the "note" style.

CategoryType
General Notenote, tip, implement, inherit
Cautionarycaution, warning, important
Securitysecurity
Language Notecs, CSharp, c#, C#, vb, VB, VisualBasic, cpp, CPP, c++, C++

Inline formatting

Inline formatting tags are typically used inside the other section and block tags to provide formatting such as the c tag or links to other API topics such as the see tag.

see

The see tag lets you to insert an inline link. Use seealso to indicate that text should be placed in the See Also section. Use the cref attribute to create internal hyperlinks to documentation pages for code tags or the href attribute to specify the URL of an external website or resource to which the link should be connected.

Internal Reference

<see cref="member" />

or

<see cref="member">inner text</see>

See the cref Attribute documentation for the information on how to structure internal hyperlinks within your API.

External Reference

<see href="url" [target="_blank | _self | _parent | _top"] [alt="alternate text"] />

or

<see href="url" [target="_blank | _self | _parent | _top"] [alt="alternate text"]>inner text</see>

c

The c tag is used to indicate that text within a description should be marked as code. Use this tag to mark inline text as code. Use the code tag to mark a multi-line block of lines as code.

Syntax:

<c>text</c>

paramref

The paramref tag is used to indicate that a word in the comments refers to a parameter, typically a method parameter. This inline tag can be used within any other tag. paramName is the name of the parameter being referenced.

Syntax:

<paramref name="paramName" />

typeparamref

The typeparamref tag is used to indicate that a word in the comments refers to a type parameter on a generic type. can be used within any other tag on a generic type or its members. typeParamName is the name of the parameter being referenced.

Syntax:

<paramref name="paramName" />

Other

exclude

The exclude tag is used to indicate that a particular type or member should be excluded from the documentation. This tag takes precedence over all other visibility options and the type or member will not appear in the resulting help file at all. Be aware that if used on an overloaded member, all versions of the overloaded member will be removed from the documentation.

Syntax:

<exclude />

When exclude is used in front of

Member
Excludes the member from help documentation
Type
Excludes the type and all its members from help documentation
Namespace
Excludes only the namespace information from help documentation. All namespace types are included into the help unless explicitly excluded

Sample XML Comment

Here is sample XML Comment:

/// <summary>
/// Finds the last item in a collection that satisfies the condition
/// defined by <paramref name="predicate"/>.
/// </summary>
/// <remarks>
/// <para>If the collection implements IList&lt;T&gt;, then the list is scanned in reverse until a 
/// matching item is found. Otherwise, the entire collection is iterated in the forward direction.</para>
/// <para>If the default value for T could be present in the collection, and 
/// would be matched by the predicate, then this method is inappropriate, because
/// you cannot distinguish whether the default value for T was actually present in the collection,
/// or no items matched the predicate. In this case, use TryFindFirstWhere.</para>
/// </remarks>
/// <param name="collection">The collection to search.</param>
/// <param name="predicate">A delegate that defined the condition to check for.</param>
/// <returns>The last item in the collection that matches the condition, or the default value for T
/// (0 or null) if no item that matches the condition is found.</returns>
/// <seealso cref="TryFindLastWhere"/>
public static T FindLastWhere<T>(IEnumerable<T> collection, Predicate<T> predicate)

Sample Help Documentation

Here is sample help documentation for the comment above:

Feedback

Does GhostDoc support cret attribute prefixes such as M: or P:? It either offers no support, or I need to turn something on.
Nicole C. Tedesco (1/1/2019 at 1:07 AM)
Yes, GhostDoc does supports the cref attribute prefixes.
Misha Zhutov (1/3/2019 at 2:25 PM)