一、概述
程序的注释在程序的编写和维护中扮演着相当重要的角色,在生成工程的同时,说明文档也随之而生了。.NET文档生成工具用于将xml 文档注释生成格式类似MSDN的HTML帮助文档,并编译为CHM文档(下文中将该工具称为ADB,该软件仅测试过.net2.0的程序集)。
二、ADB2.2的功能特点
1、支持合并多个程序集;
2、自动搜索程序集及其引用的程序集对应的XML文档(包括.Net自带的程序集,如:system.xml);
3、灵活控制在文档中显示哪些成员,支持批量选择(如:选择所有公共的方法);
4、支持自定义文档生成器,用户可以通过继承ADB提供的基类编写自己的文档生成器。
三、ADB2.2支持的注释标记
标志名
说明
语法
参数
<summary>
对象的摘要,用于描述类型或类型成员
<summary>description</summary>
description:对象的摘要。
<remarks>
类型说明的补充信息
<remarks>description</remarks>
description:成员的说明。
<param>
用于方法声明的注释中,以描述方法的一个参数
<param name='name'>description</param>
name:方法参数名。将此名称用双引号括起来 (" ")。
description:参数说明。
<returns>
用于方法声明的注释,以描述返回值
<returns>description</returns>
description:返回值的说明。
<value>
描述属性所代表的值
<value>property-description</value>
property-description:属性的说明
<example>
指定使用方法或其他库成员的示例,通常涉及使用 <code> 标记
<example>description</example>
description: 代码示例的说明。
<code>
提供了一种将多行指示为代码的方法。
<code>content</code>
content:希望将其标记为代码的文本。
<exception>
指定哪些异常可被引发,该标记应用于方法定义。
<exception cref="member">description</exception>
cref:对可从当前编译环境中获取的异常的引用。
description:异常的说明。
<see>
从文本内指定链接
<see cref="member"/>
cref:对可以通过当前编译环境进行调用的成员或字段的引用。
<para>
<para> 标记用于诸如<summary>,<remarks> 或 <returns> 等标记内,使您得以将结构添加到文本中。
<para>content</para>
content:段落文本。
<code>*
提供了一种插入代码的方法。
<code src="src" language="lan" encoding="c"/>
src:代码文件的位置
language:代码的计算机语言
encoding:文件的编码
<img>*
用以在文档中插入图片
<img src="src"/>
src:图片的位置,相对于注释所在的XML文件
<file>*
用以在文档中插入文件,在页面中表现为下载链接
<file src="src"/>
src:文件的位置,相对于注释所在的XML文件
<localize>*
提供一种注释本地化的方法,名称与当前线程语言不同的子节点将被忽略
<localize>
<zh-CHS>中文</zh-CHS>
<en>English</en>
...
</localize>
注:
1、*表示ADB自带的文档生成器扩展的标记;
2、其它不支持的标志将视为HTML标记。
四、生成文档
1.步骤
(1) 点击添加,选择要生成文档的程序集;
(2) 选择将在文档中显示该成员;
(3) 输入标题,点击创建文档。
2.主界面
3.批量选择界面
4.生成的文档——命名空间页面
5.生成的文档——类型页面
6.生成的文档——成员页面
五、修改生成的文档
使用SuperCHM或其它CHM制作工具,打开Pages"temp.hhp(相对于生成的CHM文件)文件进行修改,修改前请阅读与目标CHM文件同目录下的"修改文档.html"文件