.net 函数注析
这段写在函数前面
/// <summary>
///在这里写注析
/// </summary>
<summary> 标记用于对类型或成员的摘要说明。
<summary>description</summary>
其中:
description
对类型或成员的摘要说明。
应用于
所有的类型及成员。
备注
此标记是所有类型及成员最基本的说明，一般的，应为每个公共的、可见的类型/成员书写 summary 文档。在 Visual Studio .NET IDE 的智能感知功能及对象查看器，还有其他大多数开发工具，都会显示 summary 信息。
NDoc 将标记区分为三类: Section 标记，Block 标记，Inline 标记。
Section 标记
Section 标记用于定义不同的代码文档的区域。它们都是顶级标记，Block 标记、Inline 标记都应包含在某个 Section 标记的内部。（除非自定义了扩展 XSLT 转换，否则，在 Section 标记外部的 Block 标记或 Inline 标记都被忽略。）
| 标记 | 说明 |
|---|---|
|
<event> [NDoc 扩充] |
对某个成员可能引发的事件的说明。 |
|
<example> |
“示例”，帮助类库使用者理解类型/成员使用方法的示例代码。 |
|
<exception> |
对某个成员可以抛出的异常的说明。 |
|
<exclude/> [NDoc 扩充] |
指示 NDoc 文档引擎将被标记的类型/成员排除在代码文档之外。 与文档引擎的“可见性”配置不符的，以 exclude 优先。 |
|
<include> |
将代码文件外部的某 XML 文件中的一部分包含进代码文件来。 |
|
<overloads> [NDoc 扩充] |
为“重载列表”页面准备摘要、备注、示例等文档内容。只需在重载成员的第一个成员前面书写此区域即可。 <overloads> 标记有两种形式:
示例: ///<overloads>This method has two overloads.</overloads> ///<summary>This overload just says hello.</summary> public void SayHello() { ... } ///<summary>This one says hello to someone.</summary> public void SayHello(string toSomeone) { ... } |
|
<param> |
成员的参数说明。 |
|
<permission> |
访问某成员所必需的 .NET Framework 安全性 CodeAccessPermission。 |
|
<preliminary> [NDoc 扩充] |
将某类型/成员标记为“预发布”。内部的文本被当作警告文本用红色显示，可以包含 <para> 表示多行文本。如果缺少内部文本，则显示默认的警告文本: “[此文档为预发布版本，在未来版本中有可能改变。]”。 如果需要把全部类型/成员都标记为“预发布”，请使用文档引擎的 Preliminary 配置项。 |
|
<remarks> |
“备注”，对 <summary> 的进一步注解。 |
|
<returns> |
“返回值”。 |
|
<seealso> |
向页面的“请参见”区域添加一个链接。 请不要将此标记包含在 <remarks> 内部，它是一个顶级标记。 两种可选的语法:
|
|
<summary> |
“摘要”，对类型/成员的摘要说明。 |
|
<threadsafety> [NDoc 扩充] |
“线程安全”，说明类型在多线程环境中是否安全。 NDoc 提供 static 和 instance 两个布尔的属性，可以自动生成像 .NET Framework SDK 类库文档中那样的标准文本。 threadsafety 标记内部可以包含额外的文本，会被显示到标准文本的下方，说明额外的信息。例如: /// <summary>The summary description for SafeClass.</summary> /// <threadsafety static="true" instance="true"> /// <para>More information about using this class across thread</para> /// </threadsafety> public class SafeClass() { ... } |
|
<value> |
“属性值”。 |
Block 标记
Block 标记用于 Section 标记的内部，它们将显示在单独的行中。
| 标记 | 说明 |
|---|---|
|
<code> |
多行的代码块。 |
|
<list> |
一个列表或表格。 |
|
<note> [NDoc 扩充] |
“注意”块。 例如: /// <summary> /// <note>This is a note in the summary.</note> /// </summary> public class SomeClass() { ... } 将生成: 注意 This is a note in the summary. |
|
<para> |
表示一个段落。 |
Inline 标记
Inline 标记可以用于其他 Section 标记或 Block 标记内部，它们将和前后的文本显示在同一行中。
| 标记 | 说明 |
|---|---|
|
<c> |
将内部文本格式化为代码样式，用于表示行文中提到的短小代码片段。 |
|
<paramref> |
加入指向方法参数的链接。 |
|
<see> |
加入指向某个类型/成员或网络 URL 的链接。 两种可选的语法:
|
