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

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

用法： text 

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

/// 

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

用法： content 

将多行文本标记为代码。

用法： "member"/> 

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

/// 

/// Initializes a new instance of the  class.
/// 
/// The repository.
public DefaultAuthenticationService(IRepository repository)
{
    this.repository = repository;
}

用法： description 

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

/// 

/// The GetZero method.
/// 
///  
/// This sample shows how to call the  method.
/// 
/// class TestClass 
/// {
///     static int Main() 
///     {
///         return GetZero();
///     }
/// }
/// 
/// 
public static int GetZero()
{
    return 0;
}

View Code

用法： "name">description 

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

用法： "name"/> 

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

/// 

/// Gets a collection of membership users where the user name contains the specified user name to match.
/// 
/// The user name to search for.
/// The index of the page of results to return.  is zero-based.
/// The size of the page of results to return.
/// The total number of matched users.
/// 
/// A  collection that contains a page of  objects beginning at the page specified by .
/// 
public IList FindUsersByName(string usernameToMatch, int pageIndex, int pageSize, out int totalRecords)
{
    return GetUsers(pageIndex, pageSize, out totalRecords, u => u.UserName.Contains(usernameToMatch));
}

用法： description 

用于描述返回值。

用法： 

description

 

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

用法： "name">description 

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

/// 

/// Creates a new array of arbitrary type 
/// 
/// The element type of the array
/// 
/// 
public static T[] mkArray(int n)
{
    return new T[n];
}

用法： "name"/> 

用于引用泛型参数。

　

用法： property-description 

用于描述属性所代表的值。 请注意，当在 Visual Studio .NET 开发环境中通过代码向导添加属性时，它将会为新属性添加

标记。 然后，应该手动添加 标记以描述该属性所表示的值。例如：

/// 

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

用法： "member">description 

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

/// 

/// Gets the and validates property.
/// 
/// Name of the property.
/// Reflection property info object
/// Model has no such property
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

 

转载于:https://www.cnblogs.com/CCHUncle/p/5235727.html