XML注释是什么
在VS中编写C#代码时，如果在类、变量、方法等上方连续输入三个“/”，VS会自动为我们生成一段XML注释模板。通过这段模板，我们可以将代码的注释规范化，形成一份XML注释文档（可以在项目“生成”设置中对保存路径进行配置）。这样，不仅VS可以读取，还可以让如Swagger等第三方插件使用。
以下代码展示了常用的文档标记：
/// <summary>
/// 动物工厂
/// </summary>
public class AnimalFactory
{
/// <summary>
/// 创建类型为 <typeparamref name="TAnimal"/> 的动物
/// </summary>
/// <typeparam name="TAnimal">动物的类型</typeparam>
/// <param name="name">动物的名字</param>
/// <returns>一个继承于 <see cref="Animal"/> 抽象类的实体</returns>
/// <exception cref="ArgumentException">当 <paramref name="name"/> 为 <c>null</c>、<c>""</c> 或空白字符串时抛出</exception>
/// <example>
/// 你可以通过如下方式创建 <see cref="Dog"/> 的实例
/// <code>
/// var dog = AnimalFactory.CreateAnimal{Dog}(“小白”);
/// Console.WriteLine(dog.Name);
/// </code>
/// </example>
/// <remarks><see cref="CreateAnimal{TAnimal}(string)"/> 是 <c>AnimalFactory</c> 的静态方法</remarks>
public static TAnimal CreateAnimal<TAnimal>(string name) where TAnimal : Animal, new()
{
if (string.IsNullOrWhiteSpace(name))
throw new ArgumentException("动物名字不能为空", nameof(name));
return new TAnimal()
{
Name = name
};
}
}
/// <summary>
/// 动物
/// </summary>
public abstract class Animal
{
private string _name;
/// <summary>
/// 名字
/// </summary>
/// <value>Name属性 get/set 的值是字符串字段：_name</value>
public string Name
{
get => _name;
set => _name = value;
}
}
/// <summary>
/// 狗
/// </summary>
public class Dog : Animal
{
}
将dll与xml提供给他人使用时，VS中看到的就是这样：
//
// 摘要:
// 动物工厂
public class AnimalFactory
{
public AnimalFactory();
//
// 摘要:
// 创建类型为 TAnimal 的动物
//
// 参数:
// name:
// 动物的名字
//
// 类型参数:
// TAnimal:
// 动物的类型
//
// 返回结果:
// 一个继承于 ConsoleAppForXML.Animal 抽象类的实体
//
// 异常:
// T:System.ArgumentException:
// 当 name 为 null、"" 或空白字符串时抛出
//
// 言论：
// ConsoleAppForXML.AnimalFactory.CreateAnimal``1(System.String) 是 AnimalFactory
// 的静态方法
public static TAnimal CreateAnimal<TAnimal>(string name) where TAnimal : Animal, new();
}
XML文档标记
<summary></summary>：描述标注的类型或成员信息<typeparam name=""></typeparam>：描述泛型类型的信息- name：泛型类型的名称
<typeparamref name=""/>：按住“Ctrl”键可以导航到该泛型类型- name：泛型类型的名称
<param name=""></param>：描述方法参数- name：参数的名称
<paramref name="name"/>：按住“Ctrl”键可以导航到该参数- name：参数的名称
<returns></returns>：描述方法返回值<see cref=""/>：按住“Ctrl”键可以导航到该标记（如类、变量等）- cref：标记名称
<exception cref=""></exception>：描述方法内可能抛出的异常类型- cref：异常类型
<c></c>：标记其中的内容为代码，并且只有一行<code></code>：标记其中的内容为代码，可以有多行<example></example>：提供使用该成员的示例代码，通常与<code></code>一起使用<remarks></remarks>：提供更多备注信息<value></value>：指示属性 get/set 操作的字段
个人认为，规范的XML注释文档在项目开发和维护时可以起到事半功倍的作用，尤其是对外提供API时尤为明显。而且，规范的代码结构可以提高自己的代码质量，还可以给他人留下严谨负责的好印象。