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.
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#, CSharp | C# |
VB, vbnet, VB.NET | VB/VB.NET |
cpp, C++ | C++ |
js, jscript, JavaScript | JavaScript |
htm, html, xml, xsl | XML/HTML |
XAML | XAML |
sql | SQL |
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.
Category | Type |
---|
General Note | note, tip, implement, inherit |
Cautionary | caution, warning, important |
Security | security |
Language Note | cs, 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<T>, 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: