Click here to Skip to main content
15,867,453 members
Articles / Programming Languages / C#

ADB - Documentation Compiler for Managed Class Libraries

Rate me:
Please Sign up or sign in to vote.
4.60/5 (4 votes)
8 Mar 2009CPOL1 min read 30.7K   834   29   4
ADB produces MSDN style documentation by reflecting and integrating XML Documentation Comments.

Introduction

ADB produces MSDN style documentation by reflecting and integrating XML documentation comments. ADB has the following key features:

  1. Merge multiple assemblies in a document.
  2. Auto search XML documentation comment file of assemblies and their dependent assemblies.
  3. Extent XML documentation comments tags according to your needs.
  4. Develop custom document builder according to your needs.

Instructions

clip_image001_3.gif

Develop Custom Document Builder

Extent XML Documentation Comments Tag

ADB supports developing a custom document builder according to your needs. The following is an example developing a custom document builder named “MyBuilder” that extends the following features:

  1. Extend an <image> tag for inserting images to the document.
  2. Insert a section named “Custom Section” to the type page and member page.

Steps:

  1. Click then menu Tool->Generate Custom Builder Solution->Extent XML Comments Tag, then input the information of the custom builder:
  2. clip_image003_3.jpg

  3. Click “OK”, ADB will generate a solution for you and open the solution.
  4. Open the “MyBuilder.cs” file and input the following code:
  5. C#
    using System;
    using System.Collections.Generic;
    using System.Text;
    using ADB.Factories;
    using Microsoft.VisualBasic.FileIO;
    
    namespace ADB.Builders
    {
        public class MyBuilder : ADB.Factories.MSDNStyleCHMDocumentBuilder
        {
            static PageSection[] _memberPageSections, _typePageSections;
    
            public MyBuilder(IGetData data, IInteract interact)
                : base(data, interact)
            {
                //insert a custom section named "Custom Section" into member pages
                _memberPageSections = new PageSection[base.MemberPageSections.Length + 1];
                base.MemberPageSections.CopyTo(_memberPageSections, 0);
                _memberPageSections[base.MemberPageSections.Length] =
                    new PageSection("Custom Section", 
                    PageSectionType.FromXML, "CustomSection");
    
                //insert a custom section named "Custom Section" into type pages
                _typePageSections = new PageSection[base.TypePageSections.Length + 1];
                base.TypePageSections.CopyTo(_typePageSections, 0);
                _typePageSections[base.TypePageSections.Length] =
                    new PageSection("Custom Section", 
                    PageSectionType.FromXML, "CustomSection");
            }
    
            public override PageSection[] MemberPageSections
            {
                get
                {
                    return _memberPageSections;
                }
            }
    
            public override PageSection[] TypePageSections
            {
                get
                {
                    return _typePageSections;
                }
            }
    
            protected override string GetTag(System.Xml.XmlElement elem, string xmlFile)
            {
                switch (elem.Name)
                {
                    case "CustomSection":
                    {
                        //Generate content of CustomSection tag
                        //The content will display in the "Custom Section" 
                        //Section in member pages and type pages
                        return GetInnerTags(elem, xmlFile);
                    }
                    case "image":
                    {
                        StringBuilder tag = new StringBuilder();
                        string src = elem.GetAttribute("src");
                        if (!string.IsNullOrEmpty(src))
                        {
                            try
                            {
                                //Copy the image to the directory that cache page files.
                                FileSystem.CopyFile(xmlFile + "\\" + 
                                  src, HtmlFileDirectory + 
                                  "\\" + src, true);
                            }
                            finally
                            {
                            }
                            //Generate HTML tag
                            tag.AppendFormat("<img src='{0}'/>", src);
                        }
                        return tag.ToString();
                    }
                    default:
                    {
                        return base.GetTag(elem, xmlFile);
                    }
                }
            }
        }
    }
  6. Build the solution and click the Debug button to start ADB to debug the custom builder:
  7. clip_image005_3.jpg

  8. Testing:
  9. The following is the class and its comments for testing:

    C#
    namespace ClassLibrary1
    {
        /// <summary>
        /// Comments for Class1
        /// </summary>
        /// <CustomSection>
        /// <image src='1.gif'/>
        /// </CustomSection>
        public class Class1
        {
        }
    }

    The document generated by MyBuilder:

    clip_image007_3.jpg

  10. Let ADB load MyBuilder when starting:
  11. Open the base directory of ADB and create a folder named “MyBuilder” in “builders”, then copy “MyBuilder.dll” and “MyBuilder.builder” to the “MyBuilder” directory (as shown):

    3.GIF

    4.PNG

License

This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)


Written By
Software Developer
China China
This member has not yet provided a Biography. Assume it's interesting and varied, and probably something to do with programming.

Comments and Discussions

 
QuestionWhat is wrong with Sandcastle? Pin
sdahlbac8-Mar-09 22:20
sdahlbac8-Mar-09 22:20 
AnswerRe: What is wrong with Sandcastle? Pin
luchuncheng8-Mar-09 23:14
luchuncheng8-Mar-09 23:14 
GeneralRe: What is wrong with Sandcastle? Pin
Indivara30-Jul-09 13:40
professionalIndivara30-Jul-09 13:40 
GeneralRe: What is wrong with Sandcastle? Pin
ddarko1003-Nov-09 8:07
ddarko1003-Nov-09 8:07 
Personally I prefer Sandcastle.
quite similar but to each his own I guess.

overall this was a great article, thanks!

------------------------------------
Danny, San Francisco Locksmith

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.