NDoc1.3.1使用手册

目录

NDoc1.3.1使用手册    1

目录    2

修改历史纪录    3

1、NDoc简介    4

2、安装（for VS2003）    4

3、使用    7

3.1 配置您的C#项目    7

3.2 "装饰"您的代码    10

3.3、新建NDoc项目    25

4 OVERLOAD（重载）    35

1、NDoc简介

NDoc 可以将 C#.NET 编译生成的程序集和对应的 /doc XML 文档，自动转换成如 .NET Framework SDK 类库文档或者 MSDN Library 在线 .NET 类库文档形式的代码文档，让您快速拥有专业级的类库API 文档。

2、安装（for VS2003）

解压后，双击"Setup.exe"进入安装界面，如下图：

 

点击"下一步"：

 

选择要安装的路径，点击"下一步"，如下图：

 

 

选择"同意"，点击"下一步"继续，再点"下一步"进行安装，如下图：

 

 

点击"关闭"完成安装，如下图：

 

 

 

3、使用

开始之前，您需要准备以下工具，HTML Help 1 文件，也就是 CHM 文件，是很常见的应用程序帮助文件格式，在 Visual Studio .NET 发布之前，MSDN 一直采用的就是 HTML Help 1 格式。

如果您准备创建 HTML Help 1 (*.CHM)文件，请确认您已经安装好 Microsoft's HTML Help Workshop。此安装包已包含必需的 HTML Help 1 编译器，在与NDoc同目录下有此安装文件（htmlhelp.EXE）,按提示安装即可。

3.1 配置您的C#项目

首先，您应该确认，您已经打开了 C# 项目的 /doc 开关，当 Visual Studio .NET 编译时，每次都会生成相应的 XML 文档。

如果没有特殊情况，请让项目输出的程序集名称和 XML 文档文件名、仅仅扩展名不同(比如程序集是 NDoc.Test.dll/NDoc.Test.exe，XML 文档是 NDoc.Test.xml)。在 NDoc 中，当您加入某程序集时，NDoc 会自动查找这样的"同名" XML 文件。如果找到，就会尝试自动将它当作该程序集的 XML 文档。这样会简化您的操作。

此处以"Example069-绘制艺术图案（1）"为例，打开"项目|属性"对话框，如下图：

 

找到"程序集名称"，如下图：

选择左框中的"配置属性"，在右侧设置 XML 文档文件为程序集名称(扩展名改为 xml)。别忘了设置此项之前，选择"所有配置"，让 Debug 或 Release 配置下，都自动生成 XML 文档，如下图：

点击"确定"。现在，每次使用 VS.NET 编译您的程序集，都会自动从源代码中提取所有的 XML 注释，生成 XML 文档文件（但是每个不同的项目都得设置一次），如下图：

如果您使用的不是 Visual Studio .NET，您同样应该尝试打开 C# 编译器的 /doc 选项。

3.2 "装饰"您的代码

您在代码中书写的 XML 注释越多，最终生成的代码文档越专业。程序集的使用者越能从中获得帮助。

一般而言的最低要求，对于每一个公共类型，应该给它的所有公共的和受保护的成员添加 <summary> 注释，以描述该成员表示什么意义或者会做些什么动作。

可以从VS.NET的任务列表中查看是否注释完全，如下图：

双击它们就可以定位到未添加注释的位置。

如果在下面的选项中找不到"任务列表"，可以点击"视图|其它窗口|任务列表"打开，如下图：

在 VS.NET 中，C# 代码编辑器，提供了一些自动完成的功能，帮助我们创建基本的 XML 注释。

比如如下的代码:

public class MyClass() {

public MyClass( string s ) { }

}

把光标移动到 MyClass 构造函数的上面一空行，敲 '/' 键三次，VS.NET 自动创建一个 summary XML 文档块（在VS2005中更可以使用GhostDoc更方便地生成注释，详细内容请见《[技术文档]GhostDoc2.1.1使用手册》）:

public class MyClass() {

/// <summary>

///

/// </summary>

/// <param name="s"></param>

public MyClass( string s ) { }

}

这种操作对于所有可以书写 XML 注释文档的成员都有效。另外，在以 '///' 开头的 XML 注释行中，敲入 '<' 字符，VS.NET 自动感知功能将自动显示可用的 XML 注释标记列表。不过，这个列表不包括 NDoc 所支持的额外的标记，这些额外的标记，您需要手工敲入。

NDoc 可以配置为输出所有的成员，包括私有的和内部的成员，虽然这些成员无法在程序集外部被调用，但如果您需要，您可以同样为这些成员添加 XML 注释，NDoc 会帮您生成这样的适合内部使用的代码文档。

3.2.1 NDoc支持的标记

下面以ClassLibrary为例，介绍下NDoc支持的标记，由于为了多介绍，某些方法用了过多的标记，您可以根据自己的需要有选择地为您的代码添加。以下是标记与导出文件的效果对比（下文中的图截自VSS中与此文档同目录的同名压缩文件，以其中的MaxValue（int32）为主）：

<c>

从图中可看出，添加<c>标记后，文字的颜色发生了变化，而且字体也跟代码的字体一样。

<c>标记指示将其内部的文本表示为代码样式，Inline标记，用于表示行文中的代码片断。

应用于其他代码内部。

<code>

<code>标记表示将其内部的文本表示为代码样式，Block标记，用于表示多行的代码块。在其前标记内还可以加入属性，比如：

<code [lang = "language"][escaped = "true"]>content</code>

其中：

lang = "language"

语言选择器，表示此代码块仅适用于某种语言。（可选）

escaped = "true"

若content中含有XML子级，将它们视为代码的一部分。注意：content仍然需要时格式完好的XML。（可选）

Content

将被表示为代码块的文本

可应用于其它Senction标记或Block标记内部。

<example>

如图，<example>标记表示"示例"区域，Section标记，用于书写能辅助使用者理解并快速上手的代码示例等内容。

应用于所有类及成员。

此标记通常于<code>标记联用。

<list>

<list>标记表示一个列表（数字列表或符号列表），或一个表格，或一个定义表。Block标记。

<list>表格可以表示为四种样式，<list type = "bullet"|"number"|"table"|"definition">，具体见上表。

<note>

<note>标记表示一个"注意"块。

可用于其他标记内部。

其中的参数有：

caution将显示为"警告"，inheritinfo将显示为"对继承者的说明"（本例即为此），implementnotes将显示为"对实施者的说明"。

<overloads>

<overloads>标记为"重载列表"提供文档。

应用于属性，方法，运算符。

此标记只需要在重载成员的第一个成员前面书写此区域即可。此标记有两种形式：

简单的形式，直接在overloads里面写文本，这些文本被处理为"重载列表"的摘要。没有备注，示例等区域（如上图）。

复杂的形式，在overloads内部，包含 summary, remarks, example 等标记分别表示"重载列表"页面的摘要、备注、示例等，格式如下：

      <overloads>

      <summary>summary_description</summary>

      [<remarks>remarks_description</remarks>]

      [<example>examples_description</example>]

</overloads>

<para>

<para>标记表示一个段落，此标记亦有参数<apra lang = "language">同<code>一样，也是语言选择器。

此标记应用于其他标记内部，但经常用于<summary>,<remarks>及<return>等标记内部。

<param>

此标记乃用来描述方法的参数的，相信您不陌生。

<paramref>

此标记引用一个参数，将以代码形式表示该代码名称（功能于<code>有点相像）。

<permission>

此标记说明访问某成员所必需的.Net Framework安全性CodeAccessPermission。

其中：

     cref = "…"

表示需要的 CodeAccessPermission 类型。书写时，如果 CodeAccessPermission 是同一命名空间下的类型，member 可以直接写其名称（注意大小写）；如果是其他命名空间的，建议您写该 CodeAccessPermission 的完全限定名称。C# 编译器将检查该 CodeAccessPermission 是否存在。在输出的 XML 文档文件中，C# 编译器会自动转换简写的 member 为完全限定名称。

<preliminary>

<preliminary>标记将类型或成员标记为预发布版本，使之一直显示在显示框的顶部。

若标记中没有指定内容，则以红色显示默认的文本: "[此文档为预发布版本，在未来版本中有可能改变。]"

<remarks>

<remarks>标记表示对类型或成员的"备注"。<remarks>标记用于对<summary>摘要信息的补充。

<returns>

<returns>标记用于说明方法的返回值。

<seealso>

<seealso>标记用于在页面的"请参见"区域添加一个超链接。

完整的形式为：

    <seealso cref="member">[label]</seealso>

或
			

<seealso href="URL">[label]</seealso>

其中：

label

超链接的显示文本。

cref = "member"

表示要链接到的类型(成员)。书写时，如果要链接到的类型(成员)是同一命名空间(类型)中的类型(成员)，member 可以直接写它的名称（注意大小写）；如果是其他命名空间(类型)的，建议您写该类型(成员)的完全限定名称。C# 编译器将检查该类型(成员)是否存在。在输出的 XML 文档文件中，C# 编译器会自动转换简写的 member 为完全限定名称。

href = "URL"

一个网络 URL 地址。

请不要将此标记包含在<remarks>标记内部。

<summary>

<summary>标记相信您很熟悉，用于对类型或成员的摘要说明。此标记是所有类型及成员最基本的说明，一般的，应为每个公共的、可见的类型/成员书写 summary 文档。在 Visual Studio .NET IDE 的智能感知功能及对象查看器，还有其他大多数开发工具，都会显示 summary 信息。

<threadsafety>

<threadsafety> 标记用于说明类型在多线程环境中是否安全。

 

更多标记

更多标记请参见NDoc程序的"帮助|目录"下的"快速教程|"装饰"您的代码|NDoc支持的标记"。

3.2.2 上文完整的注释代码

///<overloads>This method takes the most maximum number.</overloads>

        /// <preliminary>

        /// <para>This method is just for testing right now. It might be removed in the near future.</para>

        /// <seealso cref="Class1.Main"/>

        /// </preliminary>

/// <summary>

/// <c>MaxValue</c> is a method in the <c>Class1</c> class. Accept and return an "int" parameter

/// </summary>

/// <param name="intArray">所要查找最大值的int型数组</param>

/// <returns>数组的最大值</returns>

        /// <remarks>a method in the ClassLibrary class.

        /// The <paramref name="intArrary"/> parameter takes a "int" number.

        /// </remarks>

         /// <permission cref="System.Security.PermissionSet">Everyone can access this method.</permission>

/// <example>

        /// <note type="caution">

        /// This sample shows how to call the MaxValue method.

        /// </note>

/// <code>

/// class Class1

/// {

/// public static int Main()

/// {

/// return MaxValue();

/// }

/// }

/// </code>

    /// <list type="table">

        /// <listheader>

        /// <term><c>list</c>简介</term>

        /// <description>参数</description>

        /// </listheader>

        /// <listheader>

        /// <term>bullet</term>

        /// <description>bullet为符号列表，对应于HTML中的UL列表</description>

        /// </listheader>

        /// <listheader>

        /// <term>number</term>

        /// <description>number为数字列表，对应于HTML中的OL列表</description>

        /// </listheader>

        /// <listheader>

        /// <term>table</term>

        /// <description>table为表格，以表格形式表示（此处即为表格）</description>

        /// </listheader>

        /// <listheader>

        /// <term>definition</term>

        /// <description>definition为定义列表</description>

        /// </listheader>

        /// </list>

        /// <note type="inheritinfo">

        /// 注意事项

        /// </note>

/// </example>

 

 

3.3、新建NDoc项目

3.3.1 添加整个项目

如果您使用 Visual Studio.NET 开发工具，那么最简单的方法就是点击工具条中的"从 Visual Studio .NET 解决方案新建 NDoc 项目..."按钮，如下图：

 

 

此处以test为例（注意：程序不支持中文路径和中文名），如下图：

 

然后，NDoc 会要求您选择某种编译配置(如 Debug 或 Release，或者其他您自定义的编译配置)，这取决于您将使用哪种编译配置下生成的程序集和 XML 文档，如下图：

"确定"之后，NDoc 项目设计器将自动生成一个新的 NDoc 项目，其中已包含解决方案中各个项目生成的程序集和相应的 XML 文档（注意：请确保项目配置中已打开XML文档输出功能，否则NDoc的输出效果将非常有限），如下图：

在HtmlHelpName中填入要生成的文件名，如下图：

同时，为了突出版权，还要给生成的文档添加Title，标上整个项目的名称（朗志轻量级项目管理文档），如下图：

按快捷键"Ctrl+Shift+B"或工具栏中的"生成文档"键生成文档，如下图：

 

在与"test"同目录下的\doc目录下即可看到生成的文档"test.chm"，如下图：

则生成的Title如下图：

您所注释的代码与所生成的相比如下图：

如果您没有使用 Visual Studio .NET，则需要手工向 NDoc 项目添加要生成代码文档的程序集和相应的 XML 文档。您可以通过点击设计器重的"添加"按钮、从文件系统中浏览并选择要添加的程序集，也可以直接从 Windows 资源管理器或"我的电脑"中、直接拖动要生成代码文档的程序集、到设计器中的程序集列表框中。

请确保您打开了 /doc 文档输出的选项，否则 NDoc 输出的代码文档只能有很少的内容。

3.3.2 添加类库（".DLL"文件）

如果创建的是类库，也可以直接点击"添加"按钮直接找到目录下的".DLL"文件添加即可，其他步骤同上。

以上两种方法完全可以通用。

生成的文档的效果如图：

 

 

 

4 OVERLOAD（重载）

函数的重载允许创建同名的多个函数，这些函数可使用不同的参数类型。

例如，下面的代码，其中包含一个MaxValue（）的函数：

class Program

            {

                static int MaxValue(int[] intArray)

                {

                    int maxVal = intArray[0];

                    for(int i = 1; i < intArray.Length; i++)

                    {

                        if(intArray[i] > maxVal)

                            maxVal = intArray[i];

                    }

                    return maxVal;

                }

 

                static void Main(string[] args)

                {

                    int[] myArray = {1,8,3,6,2,5,9,3,0,2};

                    int maxVal = MaxValue(myArray);

                    Console.WriteLine("The maximum value in myArray is {0}",maxValue);

                    Console.ReadKey();

                }

            }

这个函数只能用于处理int数组，现在要为不同的参数类型提供不同名称的函数，可以把上述函数重命名为IntArrayMaxValue（），添加函数DoubleArrayMaxValue（）处理其他类型。另外，还可以在代码中添加如下函数：

…

static double MaxValue(double[] doubleArray)

                {

                    double maxVal = doubleArray[0];

                    for(int i = 1; i < doubleArray.Length; i++)

                    {

                        if(doubleArray[i] > maxVal)

                            maxVal = doubleArray[i];

                    }

                    return maxVal;

                }

…

这里的区别是使用了double值。函数名称MaxValue（）是相同的，但其签名是不同的。用相同的名称和签名定义两个函数时错误的，但因为这两个函数有不同的签名，所示是可行的。

现在有两个版本的MaxValue（），它们的参数是int和double数组，分别返回有个int或double最大值。

这种代码的优点是不必显示指定要使用哪个函数。只需提供一个数组参数，就可以根据使用的参数类型执行相应的函数。

此时，应该注意VS中的IntelliSense的另一个功能。如果在应用程序中有上述两个函数，而且要在Main（）中输入函数名称，VS就可以显示出可用的重载函数。如果输入下面的代码：

double result = MaxValue(

VS提供了MaxValue（）两个版本的信息，使用上下箭头键可以在它们之间滚动，如下图：

在重载函数时，应包括函数签名的所有方面。例如有两个不同的函数，它们分别带有值参数和引用参数：

static void showDouble(ref int val)

                {

……

 

                }

                static void showDouble(int val)

                {

……

                }

选择使用哪个版本纯粹时根据函数调用是否包含ref关键字来确定。下面的代码时调用引用版本：

showDouble(ref val);

下面的代码是调用值版本：

showDouble(val);

另外，函数还可以根据参数的个数等来区分。