C#中的XML文档注释-推荐的文档注释标记

文档注释是为了方便自己和他人更好地理解代码所实现的功能。下面记录了一些常用的文档注释标记：

<C>

用法： <c>text</c> 

将说明中的文本标记为代码。例如：

/// <summary>
/// Validates the user.
/// </summary>
/// <param name="username">The username.</param>
/// <param name="password">The password.</param>
/// <returns>
///   <c>true</c>, if username and password are equal.
/// </returns>
public bool ValidateUser(string username, string password)
{
    var userId = GetUserIdIfValid(username, password);
    return userId.HasValue && userId.Value != Guid.Empty;
}

<code>

用法： <code>content</code> 

将多行文本标记为代码。

<see>

用法： <see cref="member"/> 

用于从文本中指定链接。例如：

/// <summary>
/// Initializes a new instance of the <see cref="DefaultAuthenticationService" /> class.
/// </summary>
/// <param name="repository">The repository.</param>
public DefaultAuthenticationService(IRepository repository)
{
    this.repository = repository;
}

<example>

用法： <example>description</example> 

用于指定使用方法或其他库成员的示例。例如：

/// <summary>
/// The GetZero method.
/// </summary>
/// <example> 
/// This sample shows how to call the <see cref="GetZero"/> method.
/// <code>
/// class TestClass 
/// {
///     static int Main() 
///     {
///         return GetZero();
///     }
/// }
/// </code>
/// </example>
public static int GetZero()
{
    return 0;
}

<param>

用法： <param name="name">description</param> 

用于描述方法的一个参数。

<paramref>

用法： <paramref name="name"/> 

用于引用某个参数。例如：

/// <summary>
/// Gets a collection of membership users where the user name contains the specified user name to match.
/// </summary>
/// <param name="usernameToMatch">The user name to search for.</param>
/// <param name="pageIndex">The index of the page of results to return. <paramref name="pageIndex" /> is zero-based.</param>
/// <param name="pageSize">The size of the page of results to return.</param>
/// <param name="totalRecords">The total number of matched users.</param>
/// <returns>
/// A <see cref="T:System.Web.Security.MembershipUserCollection" /> collection that contains a page of <paramref name="pageSize" /><see cref="T:System.Web.Security.MembershipUser" /> objects beginning at the page specified by <paramref name="pageIndex" />.
/// </returns>
public IList<User> FindUsersByName(string usernameToMatch, int pageIndex, int pageSize, out int totalRecords)
{
    return GetUsers(pageIndex, pageSize, out totalRecords, u => u.UserName.Contains(usernameToMatch));
}

<returns>

用法： <returns>description</returns> 

用于描述返回值。

<summary>

用法： <summary>description</summary> 

用于描述类型或类型成员。

<typeparam>

用法： <typeparam name="name">description</typeparam> 

用于在泛型类型或方法声明的注释中描述类型参数。例如：

/// <summary>
/// Creates a new array of arbitrary type <typeparamref name="T"/>
/// </summary>
/// <typeparam name="T">The element type of the array</typeparam>
/// <param name="n"></param>
/// <returns></returns>
public static T[] mkArray<T>(int n)
{
    return new T[n];
}

<typeparamref>

用法： <typeparamref name="name"/> 

用于引用泛型参数。

<value>　

用法： <value>property-description</value> 

用于描述属性所代表的值。 请注意，当在 Visual Studio .NET 开发环境中通过代码向导添加属性时，它将会为新属性添加 <summary>标记。 然后，应该手动添加 <value> 标记以描述该属性所表示的值。例如：

/// <summary>
/// Gets or sets the title.
/// </summary>
/// <value>
/// The title.
/// </value>
public virtual string Title { get; set; }

<exception>

用法： <exception cref="member">description</exception> 

用于说明可被引发的异常。例如：

/// <summary>
/// Gets the and validates property.
/// </summary>
/// <param name="propertyName">Name of the property.</param>
/// <returns>Reflection property info object</returns>
/// <exception cref="System.InvalidOperationException">Model has no such property</exception>
private System.Reflection.PropertyInfo GetAndValidateProperty(string propertyName)
{
    var property = modelType.GetProperty(propertyName);

    if (property == null)
    {
        property = modelType.GetProperty(System.Globalization.CultureInfo.CurrentCulture.TextInfo.ToTitleCase(propertyName));

        if (property == null)
        {
            throw new InvalidOperationException(string.Format("Property {0} doesn't exist in object {1}", propertyName, modelType));
        }
    }

    return property;
}

参考文档

1. https://msdn.microsoft.com/zh-cn/library/te6h7cxs%28v=vs.110%29.aspx
2. https://docs.microsoft.com/zh-cn/dotnet/csharp/language-reference/language-specification/documentation-comments