第二步:完善自己的程序的相关注释
比如在一个函数前面输入“///”.NET会自动创建一个 summary XML 文档块:
/// <summary>
///
/// </summary>
/// <param name="s"></param>
/// <param name="s2"></param>
作用也一目了然,生成文档的时候这是很有用的。你的注释越是详细,你生成的文档就会越专业。
这里不得不对比国内和国外的情况了,国内我们的程序员往往花N多时间完成了一个不错的软件或者类库什么的,往往什么文档也没有,别人想学习,想用你的东西,往往被一对烦乱的代码堆砌,吓跑了。那么这个软件或者类库有何意义呢,能给别人带来帮助吗?国外的做法和国内的相差就太大了,他们往往花一半的时间完善他们的注释文档工作,往往10行的小代码段,会有20行的注释,这是很多人无法想象的,但是何为目光短浅,相信聪明人自然明了。
继续说我们的注释,NDoc还支持狠毒其他的标记,需要我们自己输入的,生成文档的时候会看到相应的效果,具体怎么用,往下看。
NDoc支持许多有用的标记,下面有张列表
标记 | 说明 |
[NDoc 扩充] | 对某个成员可能引发的事件的说明。 |
“示例”,帮助类库使用者理解类型/成员使用方法的示例代码。 | |
对某个成员可以抛出的异常的说明。 | |
[NDoc 扩充] | 指示 NDoc 文档引擎将被标记的类型/成员排除在代码文档之外。 与文档引擎的“可见性”配置不符的,以 exclude 优先。 |
将代码文件外部的某 XML 文件中的一部分包含进代码文件来。 | |
[NDoc 扩充] | 为“重载列表”页面准备摘要、备注、示例等文档内容。只需在重载成员的第一个成员前面书写此区域即可。 <overloads> 标记有两种形式: · 简单的形式,直接在 overload 中写文本,这些文本被处理为“重载列表”页面的摘要。没有备注、示例等区域。 · 复杂的形式,在 overload 内部,包含 summary, remarks, example 等标记分别表示“重载列表”页面的摘要、备注、示例等。 示例: ///<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) { ... } |
成员的参数说明。 | |
访问某成员所必需的 .NET Framework 安全性 CodeAccessPermission。 | |
[NDoc 扩充] | 将某类型/成员标记为“预发布”。内部的文本被当作警告文本用红色显示,可以包含 <para> 表示多行文本。如果缺少内部文本,则显示默认的警告文本: “[此文档为预发布版本,在未来版本中有可能改变。]”。 如果需要把全部类型/成员都标记为“预发布”,请使用文档引擎的 Preliminary 配置项。 |
“备注”,对 <summary> 的进一步注解。 | |
“返回值”。 | |
向页面的“请参见”区域添加一个链接。 请不要将此标记包含在 <remarks> 内部,它是一个顶级标记。 两种可选的语法: · <seealso href="http://www.microsoft.com/china/msdn/">MSDN(CHS)</seealso> · <seealso cref="System.Data.DataSet">DataSet</seealso> | |
“摘要”,对类型/成员的摘要说明。 | |
[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() { ... } |
“属性值”。 |
Block 标记
Block 标记用于 Section 标记的内部,它们将显示在单独的行中。
标记 | 说明 |
多行的代码块。 | |
一个列表或表格。 | |
[NDoc 扩充] | “注意”块。 例如: /// <summary> /// <note>This is a note in the summary.</note> /// </summary> public class SomeClass() { ... } 将生成: 注意 This is a note in the summary. |
表示一个段落。 |
Inline 标记
Inline 标记可以用于其他 Section 标记或 Block 标记内部,它们将和前后的文本显示在同一行中。
标记 | 说明 |
将内部文本格式化为代码样式,用于表示行文中提到的短小代码片段。 | |
加入指向方法参数的链接。 | |
加入指向某个类型/成员或网络 URL 的链接。 两种可选的语法: · <see href="http://www.microsoft.com/china/msdn/">MSDN(CHS)</see> · <see cref="System.Data.DataSet">DataSet</see> · <see langword="xxx"/> |
第三步:就是使用我们的NDoc工具了
如果您使用 Visual Studio.NET 开发工具,那么最简单的方法就是点击工具条中的“从 Visual Studio .NET 解决方案新建 NDoc 项目...”按钮。
然后,NDoc 会要求您选择某种编译配置(如 Debug 或 Release,或者其他您自定义的编译配置),这取决于您将使用哪种编译配置下生成的程序集和 XML 文档。
编译配置选择对话框
“确定”之后,NDoc 项目设计器将自动生成一个新的 NDoc 项目,其中已包含解决方案中各个项目生成的程序集和相应的 XML 文档。
如果您没有使用 Visual Studio .NET,则需要手工向 NDoc 项目添加要生成代码文档的程序集和相应的 XML 文档。您可以通过点击设计器重的“添加”按钮、从文件系统中浏览并选择要添加的程序集,也可以直接从 Windows 资源管理器或“我的电脑”中、直接拖动要生成代码文档的程序集、到设计器中的程序集列表框中。
请确保您打开了 /doc 文档输出的选项,否则 NDoc 输出的代码文档只能有很少的内容。选择文档引擎
NDoc 内置了若干文档引擎,它们可以用于生成不同风格、样式、格式的代码文档。每种文档引擎都定义了它自己的排版、格式,以及要输出的内容。
最受欢迎的两种文档引擎是 MSDN 和 VS.NET 2003。它们都生成类似 .NET Framework SDK 类库文档样式的代码文档,不同的是前者最终编译成 HTML Help 1 (即 *.CHM)格式的整合文件,后者最终编译成 Microsoft Help 2 (即以形如 ms-help://... 的 URI 地址访问的文档)格式的形式。
NDoc 1.3 中,新增了 MSDN 2003 文档引擎,在保留 MSDN 文档引擎的特点之外,向接近 .NET Framework SDK 类库文档的方向又前进了一大步:加入了语言选择器等特色功能。
NDoc 文档引擎
所有的文档引擎都共享一些配置项,比如要输出哪些类型/不输出哪些类型等;每种文档引擎都会有一些额外的配置项,用于特定的配置。
这里还有要说的就是这些文档引擎,需要安装相应的支持工具
HTML Help 1 编译器
HTML Help 1 文件,也就是 CHM 文件,是很常见的应用程序帮助文件格式,在 Visual Studio .NET 发布之前,MSDN 一直采用的就是 HTML Help 1 格式。
如果您准备创建 HTML Help 1 (*.CHM)文件,请确认您已经安装好 Microsoft's HTML Help Workshop。此下载安装包已包含必需的 HTML Help 1 编译器。
Microsoft Help 2 编译器
Microsoft Help 2 是 Microsoft 从 Visual Studio .NET 2002 开始使用的、一种新的帮助文档格式。
如果您准备创建 Microsoft Help 2 (*.HxS)文件,请下载并安装 Visual Studio Help Integration Kit (VSHIK)。此工具包已包含所必需的 Microsoft Help 2 编译器。
Latex 编译器
如果您准备使用 LaTeX 文档引擎创建 dvi 或 pdf 文件,您需要下载并安装一个 LaTeX 系统,比如免费的 MikTeX。
生成代码文档
选择好文档引擎,并做好相应的配置。您就可以点击“生成”按钮让 NDoc 创建您需要的代码文档了。设计器下方的“输出”窗口中将显示文档制作中的消息,状态条上的进度条指示生成的整体进度。
NDoc 生成进度
查看文档 生成成功后,您可以点击“查看文档”按钮查看生成的代码文档。
最后,希望大家用好这个小工具,让我们的程序代码更有价值。