NDoc是一个.NET代码文档生成工具，有点象JDoc,但这个是在.NET下的工具。
NDoc使用Visual Studio.NET开发过程中生成的程序集和XML文档来生成一些格式象Visual Studio.NET和.NET Frmaework SDK在线帮助文档那样的一些编译后的HTML帮助文档。
它是一个OpenSource的项目，在http://ndoc.sourceforge.net可以下载到SourceCode。
使用十分简单，例如创建一个简单的项目来看NDoc可以为我们做些什么？
创建一个简单项目叫testNDoc，只有一个WindowForm，上面有个Button,单击显示信息。
将显示信息的类封装为ShowMsg类，只有一个方法ShowMessage.
代码如下：
showMsg.cs
using
?System;
using
?System.Windows.Forms;
namespace
?testNDoc
{
????///?
????///?ShowMsg?的摘要说明。????///?显示测试信息的类
????///?????public?class?ShowMsg????{????????public?ShowMsg()????????{????????????//????????????//?TODO:?在此处添加构造函数逻辑????????????//????????}????????///?????????///?测试字符串????????///?????????private?string?testStr?=?null;
????????#region?显示信息在信息框中的公有函数????????///?????????///?显示信息在信息框中的公有函数????????///?????????///?
传递字符串参数????????public?void?ShowMessage(string?msg)????????{????????????????MessageBox.Show(addStr(msg));????????}????????#endregion????????///?????????///?增加几个字符的私有函数????????///?????????///?
传递字符串参数????????///?
返回处理过的字符串????????protected?string?addStr(string?msg)????????{????????????//?返回字符串????????????return?"StrAdd:"?+?msg;????????}????????? ??????///?????????///?test?addOk????????///?????????///?
????????///?
????????protected?string?addOk(string?msg)????????{????????????return?"Ok:"?+?msg;????????}????}
}
using
?System;
using
?System.Drawing;
using
?System.Collections;
using
?System.ComponentModel;
using
?System.Windows.Forms;
using
?System.Data;
namespace
?testNDoc
{????///?????///?Form1?的摘要说明。????///?????public?class?testNDoc?:?System.Windows.Forms.Form????{????????private?System.Windows.Forms.Button?btnShowMsg;????????private?System.Windows.Forms.Button?btnNoSummary;????????///?????????///?必需的设计器变量。????????///?????????private?System.ComponentModel.Container?components?=?null;????????public?testNDoc()????????{????????????//????????????//?Windows?窗体设计器支持所必需的????????????//????????????InitializeComponent();????????????//????????????//?TODO:?在?InitializeComponent?调用后添加任何构造函数代码????????????//????????}????????///?????????///?清理所有正在使用的资源。????????///?????????protected?override?void?Dispose(?bool?disposing?)????????{????????????if(?disposing?)????????????{????????????????if?(components?!=?null)?????????????????{????????????????????components.Dispose();????????????????}????????????}????????????base.Dispose(?disposing?);????????}????????Windows?窗体设计器生成的代码????????///?????????///?设计器支持所需的方法?-?不要使用代码编辑器修改????????///?此方法的内容。????????///?????????private?void?InitializeComponent()????????{????????????this.btnShowMsg?=?new?System.Windows.Forms.Button();????????????this.btnNoSummary?=?new?System.Windows.Forms.Button();????????????this.SuspendLayout();????????????//?????????????//?btnShowMsg????????????//?????????????this.btnShowMsg.Location?=?new?System.Drawing.Point(72,?104);????????????this.btnShowMsg.Name?=?"btnShowMsg";????????????this.btnShowMsg.Size?=?new?System.Drawing.Size(128,?32);????????????this.btnShowMsg.TabIndex?=?0;????????????this.btnShowMsg.Text?=?"ShowMsg";????????????this.btnShowMsg.Click?+=?new?System.EventHandler(this.btnShowMsg_Click);????????????//?????????????//?btnNoSummary????????????//?????????????this.btnNoSummary.Location?=?new?System.Drawing.Point(72,?160);????????????this.btnNoSummary.Name?=?"btnNoSummary";????????????this.btnNoSummary.Size?=?new?System.Drawing.Size(128,?32);????????????this.btnNoSummary.TabIndex?=?1;????????????this.btnNoSummary.Text?=?"No?Summary";????????????this.btnNoSummary.Click?+=?new?System.EventHandler(this.btnNoSummary_Click);????????????//?????????????//?testNDoc????????????//?????????????this.AutoScaleBaseSize?=?new?System.Drawing.Size(6,?14);????????????this.ClientSize?=?new?System.Drawing.Size(520,?341);????????????this.Controls.Add(this.btnNoSummary);????????????this.Controls.Add(this.btnShowMsg);????????????this.Name?=?"testNDoc";????????????this.Text?=?"testNDoc";????????????this.ResumeLayout(false);????????}????????#endregion????????///?????????///?应用程序的主入口点。????????///?????????[STAThread]????????static?void?Main()?????????{????????????Application.Run(new?testNDoc());????????}????????????????///?????????///?单击button显示信息????????///?????????///?
????????///?
????????private?void?btnShowMsg_Click(object?sender,?System.EventArgs?e)????????{????????????ShowMsg?sMsg?=?new?ShowMsg();????????????sMsg.ShowMessage("Hello?");????????}????????private?void?btnNoSummary_Click(object?sender,?System.EventArgs?e)????????{????????????ShowMsg?sMsg?=?new?ShowMsg();????????????sMsg.ShowMessage("No?Summary?Click!");????????}????}}
为了使用NDoc生成文档，必须有一个编译后的程序集和一个导出的XML文件，要生成这个XML文件，必须在项目属性中将生成XML文件的
选项填上文件名字，如下图：
编译有生成一个对应的XML文件：
打开XML文件看到以下内容(注意：这个XML文件并不是NDoc生成的，而是Visual Studio.NET生成的)：
xml?version="1.0"?><doc>????<assembly>????????<name>testNDoc
name>????
assembly>????<members>????????<member?name="T:testNDoc.testNDoc">????????????<summary>????????????Form1?的摘要说明。????????????
summary>????????
member>????????<member?name="F:testNDoc.testNDoc.components">????????????<summary>????????????必需的设计器变量。????????????
summary>????????
member>????????<member?name="M:testNDoc.testNDoc.Dispose(System.Boolean)">????????????<summary>????????????清理所有正在使用的资源。????????????
summary>????????
member>????????<member?name="M:testNDoc.testNDoc.InitializeComponent">????????????<summary>????????????设计器支持所需的方法?-?不要使用代码编辑器修改????????????此方法的内容。????????????
summary>????????
member>????????<member?name="M:testNDoc.testNDoc.Main">????????????<summary>????????????应用程序的主入口点。????????????
summary>????????
member>????????<member?name="M:testNDoc.testNDoc.btnShowMsg_Click(System.Object,System.EventArgs)">????????????<summary>????????????单击button显示信息????????????
summary>????????????<param?name="sender">
param>????????????<param?name="e">
param>????????
member>????????<member?name="T:testNDoc.ShowMsg">????????????<summary>????????????ShowMsg?的摘要说明。????????????显示测试信息的类????????????
summary>????????
member>????????<member?name="F:testNDoc.ShowMsg.testStr">????????????<summary>????????????测试字符串????????????
summary>????????
member>????????<member?name="M:testNDoc.ShowMsg.ShowMessage(System.String)">????????????<summary>????????????显示信息在信息框中的公有函数????????????
summary>????????????<param?name="msg">传递字符串参数
param>????????
member>????????<member?name="M:testNDoc.ShowMsg.addStr(System.String)">????????????<summary>????????????增加几个字符的私有函数????????????
summary>????????????<param?name="msg">传递字符串参数
param>????????????<returns>返回处理过的字符串
returns>????????
member>????????<member?name="M:testNDoc.ShowMsg.addOk(System.String)">????????????<summary>????????????test?addOk????????????
summary>????????????<param?name="msg">
param>????????????<returns>
returns>????????
member>????
members>
doc>
仔细对比这个XML文件和源代码之间的关系可以发现：
1.这个XML文件列出了大部分的方法，不管这些方法是私有，公有还是保护的，甚至构造函数；
2.region的部分并没有列入XML文件;
3.没有带注释的方法也没有列入XML文件，例如ShowMsg的构造函数和Form1.cs中的btnNoSummary_Click函数部分；
4.有注释的变量也被列入XML文件了，例如Form1.cs中的private System.ComponentModel.Container components = null和ShowMsg类
中的private string testStr = null;5.对于//这种方式的注释并没有例如文件；
小结：以下面方式的注释会列入XML文件中
????????
///?????????///?增加几个字符的私有函数????????///?????????///?
传递字符串参数????????///?
返回处理过的字符串
那么NDoc处理后又是如何的呢？
安装NDoc后运行程序，选择程序集和对应的XML文件,如下图
然后就设置生成文档的相关参数了
文档类型目前支持6种：
HtmlHelp2? 注意，这种文档需要安装Visual Studio Help Integration Kit，可以在微软网站下载；
JavaDoc??? 类似于Java API的文档方式，习惯看Java API的人比较喜欢
LaTeX (alpha)
LinearHtml (alpha)
MSDN
XML
选择不同的文档类型需要设置一些不同的参数，这里选择HtmlHelp2格式。
可以设置的参数比较多，很多可以使用默认值，每个的作用都可以在下面看到它的解释，这个例子选择的设置如下图：
选择菜单上的Documentation->Build就可以生成需要的帮助文档了。
此时就会在NDoc文件所在目录下生成一个doc目录，全部生成的文件都放在这个目录下。
打开NDocTest.chm，看到的效果如下：
这里可以看到生成的信息并不是单单依赖于上面讨论的XML文件，也生成了很多完整的信息，这些信息应该通过反射机制在程序集中读取的。
对比结果可以看到：
1.生成的CHM只显示了public和protected，而private则没有显示，不管是否在XML有反应；
2.继承过来的方法也会在CHM中显示出来；
3.生成的CHM主要以程序集为基础，将public和protected的方法显示出来，而XML主要作为注释的参考，例如项目中有些没有注释的共有方法在XML中没有反应出来，但是在CHM也会显示出来。
小结：NDoc生成的CHM并没有完全将项目中的全部注释抽取出来，但是它作为生成API文档则是十分有用的。
另外值得注意的是：
在使用中发现NDoc的同步似乎有些问题，例如第一次生成后，对有些方法做了些修改，注释的修改可以同步更新，但一些方法的属性变更并没有直接反应过去，例如将public改成protected，在生成的CHM中也不会直接反应。
?
====================
NDoc中的一些参数设置可以控制生成显示，如下图：
将DocumentPrivates打开则可以显示private的方法了。
234
扫一扫
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
