扩展 NDoc

NDoc 可扩展性

MSDN, MSDN 2003 和 VS.NET 文档引擎都支持一个可扩展的模型，允许您定义自己专有的标记，并指定它们在代码文档中呈现的样式。您或许已经知道，这些文档引擎都使用 XSLT 转换，将 NDoc 中间 XML 数据文件转换为目标 HTML 格式。NDoc 标记的可扩展性也依赖于此，您可以通过自定义的 XSLT 转换文件加入您自定义的标记。（建议，您需要事先了解一些 XSLT 转换的知识，并分析 XML 文档引擎生成的 NDoc 中间 XML 数据文件中的 XML 格式，经过足够的测试，以调试您自己的扩展 XSLT 转换。）

第一步，是在您的 C# 代码中加入您的自定义标记: (注意红色的自定义标记)

[C#]

/// <myTag>This is a custom tag</myTag>
/// <summary>
///   When processed by the VS.NET or MSDN documenters, 
///   using the stylesheet "extend-ndoc.xslt" as the ExtensibilityStylesheet 
///   property will result in end-user defined tags being displayed in the 
///   final help output topics 
/// </summary>
/// <remarks>This is a test of an inline <null/> tag</remarks>					
public class ABunchOfCustomTags
{
}

在编译后生成的 /doc 文档中，您可以找到这些自定义的标记。

接下来，创建您的 XSLT 转换模板，控制那些自定义标记的输出位置和样式:

<xsl:stylesheet version="1.0" xmlns:xsl=http://www.w3.org/1999/XSL/Transform xmlns:MSHelp="http://msdn.microsoft.com/mshelp">

       <xsl:template match="node()" mode="xml-data-island" priority="1">

              <MSHelp:Attr Name="TargetOS" Value="Windows"/>

       </xsl:template>
       <xsl:template match="ndoc" mode="header-section">

              <style type="text/css">

                     .green

                     {

                            color:green;

                     }

              </style>

       </xsl:template>
       <xsl:template match="myTag" mode="seealso-section">

              <h1 class="green">

                     <xsl:value-of select="." mode="slashdoc"/>

              </h1>

       </xsl:template>

       <xsl:template match="null" mode="slashdoc">

              <xsl:text> null reference (Nothing in Visual Basic) </xsl:text>

       </xsl:template>

</xsl:stylesheet>

您应该确认 XSLT 标记的完整和语法的正确，注意 XSLT namespace 是必须的。

如上面示例中看到的那样，使用 stylesheet 中的 templates“匹配(match)”您的自定义标记。match 是 XPath 查询的一种，指示 template 将应用于哪些标记。简单的用法是直接匹配您的自定义标记，当然还可以有更高级的用法，对 XSLT 高手们应当是小菜一碟。
注意: 如果您定义的自定义标记中还包含其他标记，您应当加入下面的命令，让它转换这些内含的标记(比如 <see> 等)：
```
<xsl:apply-templates select="." mode="slashdoc"/>
```
上例中还展示了向 HTML HEAD 头部添加附加样式定义的方法，即使用 mode 为 header-section 的 template。使用这种方法您可以覆盖 NDoc 默认的样式或者添加附加的样式表等。

什么是 mode 呢？mode 用于指定该内容将显示于文档的哪些区域。NDoc 扩展的自定义标记可以是以下两类:
1. Section 标记 - 块标记，将显示于文档的某个区域。为 section 标记编写 template 时，mode 必须是预定义的可用 Section 的列表中的一个。
2. Inline 标记 - 将和其他注释文本夹杂在一起。为 inline 标记编写 template 时，mode 必须是 "slashdoc"。
如果您准备编写匹配一些泛型 XPath 查询，如 node(), text(), *, 或 @*，您应当给该 template 指定一个名为 priority、值大于 0.5 的属性，用您编写的 template 替换 NDoc 默认的转换模板。

请注意: XSLT 是大小写敏感的，match 查询模式，以及 mode 值都必须使用正确的大小写，否则将被忽略。
最后，为 MSDN 或 VS.NET 文档引擎设置 ExtensibilityStylesheet 配置，指向您创作好的 XSLT 转换文件。然后使用 NDoc 生成代码文档，您将看到已经按照您编写的 template 规则执行了相应转换。

一张屏幕截图:

输出示例

请参见

可用 Section 的列表