Microsoft 官方文档链接:XML 文档注释
编程平台:Visual Studio 2022
编程语言:CSharp
一、为什么有此文章
如果说写程序是为了达到某种实现效果目的而做的事情,那么写注释是为了将代码负责的托付给下一位。(当然也是更快让自己失业)。在对工作上,除必要的代码行做出解释,多数情况下并不需要做到对任一的详细描述。大概一二即可,但对自己,譬如开发一套适用于个人搞搞小业务的时候。整理前后显得尤为重要。本文重点概括总结个人使用频率较高的XML关键词。
二、XML 关键词
2.1 特殊注释字段 | summary
- 常用于
Classs/Struct
、Property
、Method
、Event/Action/Delegate
,以简洁明了的描述解释用途。
2.2 概述说明字段 | remarks
- 类名的简述是必须必然的,以快速告诉开发者它的主要用途。而
remarks
等同于一段内容描述,以补充作为标题字段的Summary
所无法阐述的内容。与return
相比较,其适用属性、字段、方法、类等较为广泛。但倾向上更适用于非泛型对象。
2.3 返回结果字段 | returns
- 常用于
泛型 或 特定类型 Method
,以解释该方法返回对象或内容。但注意,无论条件是否成立,可以返回null
或new
,根据应用环境,必要时应添加结果返回说明参数。亦或是默认值。
2.4 参数注释字段 | param 与 typeparam
- 默认设置下,对不存在于该方法内的变量对象,使用该注释字段将显示白色。虽不影响代码运行,但建议删除非方法需要变量对象的XML描述项。
param
字段伴随指引方法内需引用的局部变量解释。typeparam
:用于T
泛型参数的解释
2.5 链接引用字段 | see
- 多用于引用说明,例如使用同类方法、链接地址等内容。需搭配
cref/herf
注明引用对象后,其字段内容均以蓝色超链接方式存在。cref
:用于引用类成员 + 字段herf
:用于引用链接地址