The <inheritdoc> tag lets you inherit a comment or part of a comment from a base (inherited or implemented) member or type.
VSdocman can inherit the comment even without the <inheritdoc> tag, but there are several limitations:
•The comment is only inherited if the member doesn't have any XML comment at all. This means you cannot inherit a base comment and add or override a specific part.
•You must enable inheriting in the comment templates.
•The comment is not inherited for types (classes, interfaces, ...) and constructors.
•The comment is inherited from the closest base member with a comment. You cannot specify to inherit from a different member.
The <inheritdoc> tag gives you more flexibility and overcomes all the mentioned limitations. For example, you can inherit parameter descriptions of a method while overriding just the <summary> or <remarks>. Moreover, you can inherit just a part of an existing comment, e.g. the first paragraph of <remarks>. Or you can append a new text to the base comment.
The <inheritdoc> tag is normally used as a top-level tag but it can be also used as an inline tag, e.g. inside <remarks>.
Syntax
<inheritdoc [cref="member"] [select="xpath-filter"] />
where:
cref
Optional. The cref reference to the member containing the comment to be inherited. If omitted, the closest base member with a comment will be automatically used.
select
Optional. The filter for the inherited comments. You can explicitly select the elements from the inherited comment. This attribute uses the XML XPath syntax. Refer to XPath documentation for ways to customize your <inheritdoc> use. When omitted, all elements in the current context are included. This means whole comment if the <inheritdoc> tag is a top-level tag. If the <inheritdoc> tag is inline tag, the context is the content of its parent top-level element. You can also add attributes to the XML tags or insert your own XML tags in the comments, such as <span>, and then use them in the XPath.
C#
|
 Copy Code
|
/// <summary>
/// This is the base class.
/// </summary>
/// <remarks>This class serves for demonstrating XML comment inheritance.</remarks>
public class BaseClass
{
/// <summary>
/// Performs some operation.
/// </summary>
/// <param name="x">The first parameter.</param>
/// <remarks>
/// <para>Use this method for complex tasks.</para>
/// <para>The <paramref name="x"/> must be greater than zero.</para>
/// </remarks>
public virtual void Method1(int x)
{
}
}
/// <summary>
/// This is derived class.
/// </summary>
/// <inheritdoc/>
public class DerivedClass : BaseClass
{
// Derive whole comment from a base type and override the summary.
/// <inheritdoc/>
/// <remarks>
/// <inheritdoc select="para[1]"/>
/// <para>The <paramref name="x" /> can be any integer value, whether negative or positive.</para>
/// </remarks>
public override void Method1(int x)
{
// Derive whole comment except remarks. From remarks, derive only the first <para> element
// and add a new paragraph after it.
}
/// <inheritdoc cref="String.Equals(string)" select="summary|remarks"/>
public override bool Equals(object obj)
{
// Derive summary and remarks from String.Equals (instead of default Object.Equals).
return false;
}
}
|
Visual Basic
|
Copy Code
|
''' <summary>
''' This is the base class.
''' </summary>
''' <remarks>This class serves for demonstrating XML comment inheritance.</remarks>
Public Class BaseClass
''' <summary>
''' Performs some operation.
''' </summary>
''' <param name="x">The first parameter.</param>
''' <remarks>
''' <para>Use this method for complex tasks.</para>
''' <para>The <paramref name="x"/> must be greater than zero.</para>
''' </remarks>
Public Overridable Sub Method1(ByVal x As Integer)
End Sub
End Class
''' <summary>
''' This is derived class.
''' </summary>
''' <inheritdoc/>
Public Class DerivedClass
Inherits BaseClass
' Derive whole comment from a base type and override the summary.
''' <inheritdoc/>
''' <remarks>
''' <inheritdoc select="para[1]"/>
''' <para>The <paramref name="x" /> can be any integer value, whether negative or positive.</para>
''' </remarks>
Public Overrides Sub Method1(ByVal x As Integer)
' Derive whole comment except remarks. From remarks, derive only the first <para> element
' and add a new paragraph after it.
End Sub
''' <inheritdoc cref="String.Equals(string)" select="summary|remarks"/>
Public Overrides Function Equals(ByVal obj As Object) As Boolean
' Derive summary And remarks from String.Equals (instead of default Object.Equals).
Return False
End Function
End Class
|
|
Examples