.NET文档生成工具ADB[更新至2.3]

ADB2.3下载  ADB2.3源代码下载  Microsoft HTML Help Workshop下载

注意：使用该软件需先安装Microsoft HTML Help Workshop

程序的注释在程序的编写和维护中扮演着相当重要的角色，在Visual C#中，可以为代码创建文档，方法是在XML标记所指的代码块前面，直接在源代码的特殊注释字段中包括XML 标记。编译器编译时将在源代码中搜索所有的 XML 标记，并创建一个XML文档文件。.NET文档生成工具(下文简称为ADB)通过反射程序集及其代码中的XML注释来创建MSDN形式的API文档。

1.ADB2.3的功能特性：

(1)根据程序集及其对应的XML文档文件生成风格类似MSDN的文档，并打包为CHM文件；

(2)将多个程序集对应的文档合并到一个文档中；

(3)自动搜索程序集及其引用的程序集对应的XML文档（包括.Net自带的程序集,如：System.xml）；

(4)灵活控制在文档中显示哪些成员（如：只生成公共方法）；

(5)界面友好，操作简便。

(6)用户可以根据自己的需要扩展XML标志；

(7)用户可以根据自己的需要编写自定义的文档生成器。

2.ADB2.3支持的注释标记

3.ADB2.3使用指南

ADB2.3使用方法如下图所示：

(1)主界面：

(2)批量选择:

4.生成的文档

(1)命名空间页面：

2.类型页面：

3.成员页面:

 

5.开发自定义文档生成器

ADB2.3支持加载用户自定义的文档生成器，用户可根据自己的需求开发文档生成器，下面以开发自定义文档生成器MyBuilder为例，说明如何开发自定义文档生成器：

⑴目标：

开发一个自定义文档生成器，该文档生成器在ADB默认文档生成器基础上扩展以下功能：

a.在XML文档注释可以用<image>插入图片；

b.在类型页面和成员页面中增加一个名称为“自定义节”的内容节。

⑵开发步骤

a.点击菜单 工具->生成自定义文档解决方案->扩展XML文档注释，在弹出的对话框中输入文档生成器名称

b.打开工程中的MyBuilder.cs文件，输入以下代码

using System;

using System.Collections.Generic;

using System.Text;

using ADB.Factories;

using Microsoft.VisualBasic.FileIO;



namespace CustomBuilder

{

    /// <summary>

    /// MyBuilder

    /// </summary>

    public class MyBuilder : ADB.Factories.MSDNStyleCHMDocumentBuilder

    {

        static PageSection[] _memberPageSections, _typePageSections;



        public MyBuilder(IGetData data, IInteract interact)

            : base(data, interact)

        {

            //base.MemberPageSections为页面原有的节，将自定义节插入到页面的最后

            _memberPageSections = new PageSection[base.MemberPageSections.Length + 1];

            base.MemberPageSections.CopyTo(_memberPageSections, 0);

            _memberPageSections[base.MemberPageSections.Length] = 

                new PageSection("自定义节", PageSectionType.FromXML, "CustomSection");



            //base.MemberPageSections为页面原有的节，将自定义节插入到页面的最后

            _typePageSections = new PageSection[base.TypePageSections.Length + 1];

            base.TypePageSections.CopyTo(_typePageSections, 0);

            _typePageSections[base.TypePageSections.Length] = 

                new PageSection("自定义节", PageSectionType.FromXML, "CustomSection");

        }



        //重写基类的MemberPageSections属性

        public override PageSection[] MemberPageSections

        {

            get

            {

                return _memberPageSections;

            }

        }



        //重写基类的TypePageSections属性

        public override PageSection[] TypePageSections

        {

            get

            {

                return _typePageSections;

            }

        }



        protected override string GetTag(System.Xml.XmlElement elem, string xmlFile)

        {

            switch (elem.Name)

            {

            case "CustomSection":

                {

                    //生成"自定义节"的内容

                    return GetInnerTags(elem, xmlFile);

                }

            case "image":

                {

                    StringBuilder tag = new StringBuilder();

                    string src = elem.GetAttribute("src");

                    if (!string.IsNullOrEmpty(src))

                    {

                        try

                        {

                            //将图片拷贝到生成页面的目录中

                            //（通过属性HtmlFileDirectory获取保存页面的目录）

                            FileSystem.CopyFile(

                                xmlFile + "\\" + src, 

                                HtmlFileDirectory + "\\" + src, 

                                true

                            );

                        }

                        finally

                        {

                        }

                        //生成HTML标志

                        tag.AppendFormat("<img src='{0}'/>", src);

                    }

                    return tag.ToString();

                }

            default:

                {

                    //其它标志由基类处理

                    return base.GetTag(elem, xmlFile);

                }

            }

        }

    }

}

c.点击调试按钮调试自定义文档生成器 

⑶测试

由于测试的类及其XML注释：

namespace ClassLibrary1

{

    /// <summary>

    /// Class摘要

    /// </summary>

    /// <CustomSection>

    /// 自定义的节

    /// <image src="1.gif"/>

    /// </CustomSection>

    public class Class1

    {

    }

}

用自定义文档生成器MyBuilder生成的文档

⑷让ADB启动时自动加载文档生成器

在ADB目录下新建目录MyBuilder，并将MyBuilder.dll和MyBuilder.builder拷贝到该文件夹中