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