NDoc使用简要手册

原创 2004年09月16日 09:43:00

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

None.gifusing?System;
None.gif
using?System.Windows.Forms;
None.gif
None.gif
namespace?testNDoc
ExpandedBlockStart.gif
{
ExpandedSubBlockStart.gif????
///?
InBlock.gif????
///?ShowMsg?的摘要说明。
InBlock.gif????
///?显示测试信息的类
ExpandedSubBlockEnd.gif????
///?

InBlock.gif????public?class?ShowMsg
ExpandedSubBlockStart.gif????
{
InBlock.gif????????
public?ShowMsg()
ExpandedSubBlockStart.gif????????
{
InBlock.gif????????????
//
InBlock.gif????????????
//?TODO:?在此处添加构造函数逻辑
InBlock.gif????????????
//
ExpandedSubBlockEnd.gif
????????}

ExpandedSubBlockStart.gif????????
///?
InBlock.gif????????
///?测试字符串
ExpandedSubBlockEnd.gif????????
///?

InBlock.gif????????private?string?testStr?=?null;
InBlock.gif
ContractedSubBlock.gif????????

InBlock.gif
ExpandedSubBlockStart.gif????????
///?
InBlock.gif????????
///?增加几个字符的私有函数
InBlock.gif????????
///?
InBlock.gif????????
///?传递字符串参数
ExpandedSubBlockEnd.gif????????
///?返回处理过的字符串

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

InBlock.gif????????
ExpandedSubBlockStart.gif? ??????
///?
InBlock.gif????????
///?test?addOk
InBlock.gif????????
///?
InBlock.gif????????
///?
ExpandedSubBlockEnd.gif????????
///?

InBlock.gif????????protected?string?addOk(string?msg)
ExpandedSubBlockStart.gif????????
{
InBlock.gif????????????
return?"Ok:"?+?msg;
ExpandedSubBlockEnd.gif????????}

ExpandedSubBlockEnd.gif????}

ExpandedBlockEnd.gif}

None.gif
Form1.cs
None.gifusing?System;
None.gif
using?System.Drawing;
None.gif
using?System.Collections;
None.gif
using?System.ComponentModel;
None.gif
using?System.Windows.Forms;
None.gif
using?System.Data;
None.gif
None.gif
namespace?testNDoc
ExpandedBlockStart.gif
{
ExpandedSubBlockStart.gif????
///?
InBlock.gif????
///?Form1?的摘要说明。
ExpandedSubBlockEnd.gif????
///?

InBlock.gif????public?class?testNDoc?:?System.Windows.Forms.Form
ExpandedSubBlockStart.gif????
{
InBlock.gif????????
private?System.Windows.Forms.Button?btnShowMsg;
InBlock.gif????????
private?System.Windows.Forms.Button?btnNoSummary;
ExpandedSubBlockStart.gif????????
///?
InBlock.gif????????
///?必需的设计器变量。
ExpandedSubBlockEnd.gif????????
///?

InBlock.gif????????private?System.ComponentModel.Container?components?=?null;
InBlock.gif
InBlock.gif????????
public?testNDoc()
ExpandedSubBlockStart.gif????????
{
InBlock.gif????????????
//
InBlock.gif????????????
//?Windows?窗体设计器支持所必需的
InBlock.gif????????????
//
InBlock.gif
????????????InitializeComponent();
InBlock.gif
InBlock.gif????????????
//
InBlock.gif????????????
//?TODO:?在?InitializeComponent?调用后添加任何构造函数代码
InBlock.gif????????????
//
ExpandedSubBlockEnd.gif
????????}

InBlock.gif
ExpandedSubBlockStart.gif????????
///?
InBlock.gif????????
///?清理所有正在使用的资源。
ExpandedSubBlockEnd.gif????????
///?

InBlock.gif????????protected?override?void?Dispose(?bool?disposing?)
ExpandedSubBlockStart.gif????????
{
InBlock.gif????????????
if(?disposing?)
ExpandedSubBlockStart.gif????????????
{
InBlock.gif????????????????
if?(components?!=?null)?
ExpandedSubBlockStart.gif????????????????
{
InBlock.gif????????????????????components.Dispose();
ExpandedSubBlockEnd.gif????????????????}

ExpandedSubBlockEnd.gif????????????}

InBlock.gif????????????
base.Dispose(?disposing?);
ExpandedSubBlockEnd.gif????????}

InBlock.gif
ContractedSubBlock.gif????????
Windows?窗体设计器生成的代码
InBlock.gif
ExpandedSubBlockStart.gif????????
///?
InBlock.gif????????
///?应用程序的主入口点。
ExpandedSubBlockEnd.gif????????
///?

InBlock.gif????????[STAThread]
InBlock.gif????????
static?void?Main()?
ExpandedSubBlockStart.gif????????
{
InBlock.gif????????????Application.Run(
new?testNDoc());
ExpandedSubBlockEnd.gif????????}

InBlock.gif????????
ExpandedSubBlockStart.gif????????
///?
InBlock.gif????????
///?单击button显示信息
InBlock.gif????????
///?
InBlock.gif????????
///?
ExpandedSubBlockEnd.gif????????
///?

InBlock.gif????????private?void?btnShowMsg_Click(object?sender,?System.EventArgs?e)
ExpandedSubBlockStart.gif????????
{
InBlock.gif????????????ShowMsg?sMsg?
=?new?ShowMsg();
InBlock.gif????????????sMsg.ShowMessage(
"Hello?");
ExpandedSubBlockEnd.gif????????}

InBlock.gif
InBlock.gif????????
private?void?btnNoSummary_Click(object?sender,?System.EventArgs?e)
ExpandedSubBlockStart.gif????????
{
InBlock.gif????????????ShowMsg?sMsg?
=?new?ShowMsg();
InBlock.gif????????????sMsg.ShowMessage(
"No?Summary?Click!");
ExpandedSubBlockEnd.gif????????}

ExpandedSubBlockEnd.gif????}

ExpandedBlockEnd.gif}

None.gif


为了使用NDoc生成文档,必须有一个编译后的程序集和一个导出的XML文件,要生成这个XML文件,必须在项目属性中将生成XML文件的

选项填上文件名字,如下图:
NDoc1.JPG
编译有生成一个对应的XML文件:
NDoc2.JPG
打开XML文件看到以下内容(注意:这个XML文件并不是NDoc生成的,而是Visual Studio.NET生成的):

None.gif<?xml?version="1.0"?>
None.gif
<doc>
None.gif????
<assembly>
None.gif????????
<name>testNDoc< SPAN>name>
None.gif????
< SPAN>assembly>
None.gif????
<members>
None.gif????????
<member?name="T:testNDoc.testNDoc">
None.gif????????????
<summary>
None.gif????????????Form1?的摘要说明。
None.gif????????????
< SPAN>summary>
None.gif????????
< SPAN>member>
None.gif????????
<member?name="F:testNDoc.testNDoc.components">
None.gif????????????
<summary>
None.gif????????????必需的设计器变量。
None.gif????????????
< SPAN>summary>
None.gif????????
< SPAN>member>
None.gif????????
<member?name="M:testNDoc.testNDoc.Dispose(System.Boolean)">
None.gif????????????
<summary>
None.gif????????????清理所有正在使用的资源。
None.gif????????????
< SPAN>summary>
None.gif????????
< SPAN>member>
None.gif????????
<member?name="M:testNDoc.testNDoc.InitializeComponent">
None.gif????????????
<summary>
None.gif????????????设计器支持所需的方法?-?不要使用代码编辑器修改
None.gif????????????此方法的内容。
None.gif????????????
< SPAN>summary>
None.gif????????
< SPAN>member>
None.gif????????
<member?name="M:testNDoc.testNDoc.Main">
None.gif????????????
<summary>
None.gif????????????应用程序的主入口点。
None.gif????????????
< SPAN>summary>
None.gif????????
< SPAN>member>
None.gif????????
<member?name="M:testNDoc.testNDoc.btnShowMsg_Click(System.Object,System.EventArgs)">
None.gif????????????
<summary>
None.gif????????????单击button显示信息
None.gif????????????
< SPAN>summary>
None.gif????????????
<param?name="sender">< SPAN>param>
None.gif????????????
<param?name="e">< SPAN>param>
None.gif????????
< SPAN>member>
None.gif????????
<member?name="T:testNDoc.ShowMsg">
None.gif????????????
<summary>
None.gif????????????ShowMsg?的摘要说明。
None.gif????????????显示测试信息的类
None.gif????????????
< SPAN>summary>
None.gif????????
< SPAN>member>
None.gif????????
<member?name="F:testNDoc.ShowMsg.testStr">
None.gif????????????
<summary>
None.gif????????????测试字符串
None.gif????????????
< SPAN>summary>
None.gif????????
< SPAN>member>
None.gif????????
<member?name="M:testNDoc.ShowMsg.ShowMessage(System.String)">
None.gif????????????
<summary>
None.gif????????????显示信息在信息框中的公有函数
None.gif????????????
< SPAN>summary>
None.gif????????????
<param?name="msg">传递字符串参数< SPAN>param>
None.gif????????
< SPAN>member>
None.gif????????
<member?name="M:testNDoc.ShowMsg.addStr(System.String)">
None.gif????????????
<summary>
None.gif????????????增加几个字符的私有函数
None.gif????????????
< SPAN>summary>
None.gif????????????
<param?name="msg">传递字符串参数< SPAN>param>
None.gif????????????
<returns>返回处理过的字符串< SPAN>returns>
None.gif????????
< SPAN>member>
None.gif????????
<member?name="M:testNDoc.ShowMsg.addOk(System.String)">
None.gif????????????
<summary>
None.gif????????????test?addOk
None.gif????????????
< SPAN>summary>
None.gif????????????
<param?name="msg">< SPAN>param>
None.gif????????????
<returns>< SPAN>returns>
None.gif????????
< SPAN>member>
None.gif????
< SPAN>members>
None.gif
< SPAN>doc>
None.gif

仔细对比这个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文件中

ExpandedBlockStart.gif????????///?
InBlock.gif????????
///?增加几个字符的私有函数
InBlock.gif????????
///?
InBlock.gif????????
///?传递字符串参数
InBlock.gif????????
///?返回处理过的字符串
InBlock.gif

那么NDoc处理后又是如何的呢?

安装NDoc后运行程序,选择程序集和对应的XML文件,如下图
NDoc3.JPG
然后就设置生成文档的相关参数了
文档类型目前支持6种:
HtmlHelp2? 注意,这种文档需要安装Visual Studio Help Integration Kit,可以在微软网站下载;
JavaDoc??? 类似于Java API的文档方式,习惯看Java API的人比较喜欢
LaTeX (alpha)
LinearHtml (alpha)
MSDN
XML

选择不同的文档类型需要设置一些不同的参数,这里选择HtmlHelp2格式。
可以设置的参数比较多,很多可以使用默认值,每个的作用都可以在下面看到它的解释,这个例子选择的设置如下图:
NDoc4.JPG
选择菜单上的Documentation->Build就可以生成需要的帮助文档了。

此时就会在NDoc文件所在目录下生成一个doc目录,全部生成的文件都放在这个目录下。

打开NDocTest.chm,看到的效果如下:
NDoc5.JPG
这里可以看到生成的信息并不是单单依赖于上面讨论的XML文件,也生成了很多完整的信息,这些信息应该通过反射机制在程序集中读取的。

对比结果可以看到:
1.生成的CHM只显示了public和protected,而private则没有显示,不管是否在XML有反应;
2.继承过来的方法也会在CHM中显示出来;
3.生成的CHM主要以程序集为基础,将public和protected的方法显示出来,而XML主要作为注释的参考,例如项目中有些没有注释的共有方法在XML中没有反应出来,但是在CHM也会显示出来。

小结:NDoc生成的CHM并没有完全将项目中的全部注释抽取出来,但是它作为生成API文档则是十分有用的。


另外值得注意的是:
在使用中发现NDoc的同步似乎有些问题,例如第一次生成后,对有些方法做了些修改,注释的修改可以同步更新,但一些方法的属性变更并没有直接反应过去,例如将public改成protected,在生成的CHM中也不会直接反应。

?

====================

NDoc中的一些参数设置可以控制生成显示,如下图:

NDoc6.JPG

将DocumentPrivates打开则可以显示private的方法了。

NDoc使用简要手册的补充

感谢Jam Snake在NDoc使用简要手册中的评论NDoc中的一些参数设置可以控制生成显示,如下图:将DocumentPrivates打开则可以显示private的方法了。...
  • naive1010
  • naive1010
  • 2005年10月05日 17:27
  • 1031

NDoc 用户指南(一)

欢迎使用 NDoc What's New? 已知问题 快速教程 配置您的 C# 项目 “装饰”...
  • weishaolin131083
  • weishaolin131083
  • 2011年04月18日 23:18
  • 1821

NDoc 使用

NDoc 是一个很好用的.NET小工具,它可以将 C#.NET 编译生成的程序集和对应的 /doc XML 文档,自动转换成如 .NET Framework SDK 类库文档或者 MSDN Libra...
  • zhenpingwang
  • zhenpingwang
  • 2012年02月14日 14:50
  • 117

Ndoc的使用心得

只要随便整以个XML,即可以生成相应DLL的文档
  • bookshop
  • bookshop
  • 2005年07月20日 00:00
  • 549

NDoc

1、NDoc的作用它可以将我们在代码编写过程中使用///形成的XML的注释,自动形成多种风格的类库文档。这些风格可以是JavaDoc,MSDN-html,MSDN-chm,XML等,让我们快速拥有专业...
  • iluna
  • iluna
  • 2009年11月06日 20:10
  • 981

gcc linker简要手册

名词解释: bfd (binary format description) : 是指GNU的bfd库项目,其目标是希望通过一种统一的接口来处理各种不同的目标文件。 Orphan sections ...
  • fdcp123
  • fdcp123
  • 2017年03月13日 17:36
  • 301

UBB代码简要手册

链接[URL]地址[/URL][URL=地址]说明文字[/URL][EMAIL]邮件地址[/EMAIL][EMAIL=邮件地址]说明文字[/EMAIL]贴图[IMG]图片地址[/IMG][IMG=图片...
  • kenly_zhang
  • kenly_zhang
  • 2004年10月10日 17:26
  • 860

logback 简要手册

logback 简要手册
  • idler_bm
  • idler_bm
  • 2015年05月26日 16:09
  • 802

.NET开发 程序员必备工具 -- NDoc:创建代码文档工具

  编写代码文档资料几乎总是一项令人畏惧的任务。我所说的不是早期设计文档,甚至也不是更为详细的设计文档;我说的是记录类上的各个方法和属性。 NDoc 工具能够使用反射来分析程序集,并使用从 C# XM...
  • lynnlin1122
  • lynnlin1122
  • 2008年04月08日 19:09
  • 1350

NDoc简介

1、NDoc的作用他可以将我们在代码编写过程中使用///形成的XML的注释,自动形成多种风格的类库文档。这些风格可以是JavaDoc,MSDN-thml,MSDN-chm,XML等。让我们快速拥有专业...
  • hobe
  • hobe
  • 2007年04月03日 14:49
  • 675
内容举报
返回顶部
收藏助手
不良信息举报
您举报文章:NDoc使用简要手册
举报原因:
原因补充:

(最多只允许输入30个字)