首页 / XML / 你了解C#中的XML注释吗
你了解C#中的XML注释吗
内容导读
互联网集市收集整理的这篇技术教程文章主要介绍了你了解C#中的XML注释吗,小编现在分享给大家,供广大互联网技能从业者学习和参考。文章包含3133字,纯文字阅读大概需要5分钟。
内容图文
原文:你了解C#中的XML注释吗
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时尤为明显。而且,规范的代码结构可以提高自己的代码质量,还可以给他人留下严谨负责的好印象。
内容总结
以上是互联网集市为您收集整理的你了解C#中的XML注释吗全部内容,希望文章能够帮你解决你了解C#中的XML注释吗所遇到的程序开发问题。 如果觉得互联网集市技术教程内容还不错,欢迎将互联网集市网站推荐给程序员好友。
内容备注
版权声明:本文内容由互联网用户自发贡献,该文观点与技术仅代表作者本人。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如发现本站有涉嫌侵权/违法违规的内容, 请发送邮件至 gblab@vip.qq.com 举报,一经查实,本站将立刻删除。
内容手机端
扫描二维码推送至手机访问。