NDoc 文档生成器中的 MSDN 文档引擎支持所有 C# 程序员参考(参见 .NET Framework SDK)中建议的
文档注释标记。此外,它还支持一些新的标记以及标准标记的扩展语法。支持的全部标记的语法列表如下。
节标记
节标记用来定义一个类型或者类型成员各组成部分的文档。
这些标记通常用作顶级标记。
| 标记 | 说明 |
<event> | 使用此标记来声明成员引发的事件。语法如下: ///<event cref="EventName"> /// 当.....发生时触发。 ///</event> |
<example> | “示例”节。参见 Microsoft 的定义。 如果示例中包含一个或多个 <code> 块时,it must be placed in an include file to avoid indentation problems. |
<exception> | 声明该成员可能抛出的意外类型。参见 Microsoft 的定义. |
<include> | 引用描述源代码中类型和成员的另一文件中的注释。参见 Microsoft 的定义。 |
<overloads> | 新增标记,允许您为重载的成员提供文档。您只需要为重载的第一个成员定义即可。 <overloads> 标记有以下两种形式: - 简单方式:只包含文本说明,将被视作重载成员总体的 summary。
- 详细方式:您可以提供更详细的包含 summary, remarks, example 等标记的文档。
示例: ///<overloads>此方法有两次重载。问好。</overloads> ///<summary>此方法仅问好。</summary> public void SayHello() { ... } ///<summary>此方法向某人问好。</summary> public void SayHello(string toSomeone) { ... } |
<param> | 定义方法成员的参数。参见 Microsoft 的定义。 |
<permission> | 定义成员的访问。参见 Microsoft 的定义。 |
<remarks> | “备注”节。参见 Microsoft 的定义。 |
<returns> | 定义成员的返回值。参见 Microsoft 的定义。 |
<seealso> | 为“请参见”节添加链接。参见 Microsoft 的定义。 请不要 将此标记放在 <remarks> 节中。 扩展的语法: -
<seealso href="url">[label]</seealso> -
<seealso cref="member">[label]</seealso> |
<summary> | 定义对象的摘要。参见 Microsoft 的定义。 |
<value> | 定义属性值。参见 Microsoft 的定义。 |
块标记
块标记经常用在 <remarks> 或 <example> 节内部,块内容将和前后内容不在同一行中显示。
| 标记 | 说明 |
<code> | 代码块。参见 Microsoft 的定义。 Sections containing one or more <code> blocks must be placed in an include file to avoid indentation problems. |
<list> | 定义项目列表或表格。参见 Microsoft 的定义。 |
<para> | 段落标记。参见 Microsoft 的定义。 |
Inline 标记
Inline 标记通常用在 <para> 块中。其内容和前后内容显示在同一行中。
| 标记 | 说明 |
<c> | 将其内文本显示为代码样式。参见 Microsoft 的定义。 |
<paramref> | 加入指向方法参数的链接。参见 Microsoft 的定义。 |
<see> | 可以在文本中添加指向某一成员或类型的链接。参见 Microsoft 的定义。 扩展的语法: -
<see href="url">[label]</see> -
<see cref="member">[label]</see> |