CSDN博客

img qq_net

NDoc使用简要手册

发表于2004/9/16 9:43:00  868人阅读

分类: 开发工具

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;

????????


????????
///?
????????
///?增加几个字符的私有函数
????????
///?

????????
///?传递字符串参数
????????
///?返回处理过的字符串

????????protected?string?addStr(string?msg)
????????
{
????????????
//?返回字符串
????????????return?"StrAdd:"?+?msg;
????????}

????????
? ??????
///?
????????
///?test?addOk
????????
///?

????????
///?
????????
///?

????????protected?string?addOk(string?msg)
????????
{
????????????
return?"Ok:"?+?msg;
????????}

????}

}

Form1.cs
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?窗体设计器生成的代码

????????
///?
????????
///?应用程序的主入口点。
????????
///?

????????[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>testNDocname>
????
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的方法了。

0 0

相关博文

我的热门文章

img
取 消
img