Overview

DocuPro is the premier Visual Basic add-in for creating technical documentation for Visual Basic projects. Designed to be used within the Visual Basic IDE, DocuPro simplifies the creation of quality documentation in platform independent HTML format.

Application documentation becomes more maintainable and easier to keep up to date because the information contained in the documentation is extracted directly from sections of the Visual Basic source code. Special DocuPro tags (contained in comment sections of the source code) are used to indicate what information is to be extracted by DocuPro when creating the project’s documentation.

DocuPro can be used to create two different types of documentation on the same project: user documentation and developer documentation.

User Documentation

User level documentation is designed to be used by end users of software components and is intended to be distributed with the ActiveX components (executables, DLLs and controls). This type of documentation is meant to instruct other programmers on how to use the COM objects without describing the details of the implementation.

User level documentation presents the information about all public subroutines, functions and properties of the public classes, controls and documents contained in the Visual Basic Project.

Developer Documentation

Developer level documentation is designed for software developers who will not only use the resulting ActiveX component but also maintain and extend it. This level of documentation presents the information about an entire Visual Basic project.

Developer documentation includes all of the same information as the user documentation but also adds the information pertaining to private classes, forms, modules, documents and controls. Information on all methods both public and private is also included. Additionally, properties and references summaries will be added to the developer level documentation.

Installing DocuPro

1. Place the DocuPro disk into your floppy drive.

2. Create a suitable directory and copy ALL files from the floppy or zip archive (whichever you received) to that directory. From the directory where you copied the files to run batch file regall.bat to DocuPro with your operating system.

3. Start Visual Basic 6 and Open the Immediate Window using either View->Immediate Windows ffrom the Main Menu or by pressing Ctrl+G.

4. Copy the following text to the immediate window and press enter:

5. Set obj = CreateObject(“DocuPro6.Installit”): obj.Install

You will be greeted by two message boxes informing you that DocuPro has been added to the VB 6 Add-Ins and that it has been correctly added to the registry.

Exit Visual Basic

Installation

Plugging DocuPro into Visual Basic

1) Start Visual Basic 6

2) From VB’s main menu, Select Add-Ins then Add-In Manager. You should see the Add-In Manager screen. (see below)

3) Under the Available Add-Ins you should see: “Black Box Software’s DocuPro HTML Generator.

4) Select the DocuPro Add-In and select Loaded/Unloaded to Load or Unload DocuPro. Selecting Load on Startup causes DocuPro to be loaded every time Visual Basic is run.

Using DocuPro

Starting DocuPro

DocuPro can be used once a project has been loaded into Visual Basic. To use DocuPro simply select DocuPro from the Add-Ins menu. The DocuPro wizard’s main screen (Figure 1) will appear. DocuPro operates as a wizard. This allows the selecting of options, paths and additional information in a staged manner. When the DocuPro has enough information, it will then scan the Visual Basic project and create HTML based documentation.

Selecting Documentation Type

The first form of the DocuPro wizard allows the user to specify which level of the documentation to generate.

Figure 1: Selection of documentation type

Target Folder

The next step requires the selection of a folder in which to place the generated documentation. This path may either be typed in or selected using the browse button to select the desired folder. If an attempt is made to input an invalid folder or path DocuPro will alert the user.

Figure 2: Target Folder for Documentation Selection

Footer Text/HTML

The commercial version of DocuPro allows users to include footer information on each page of documentation generated. This information can be entered as plain text or as HTML. This information is copied verbatim to the end of every page. Any HTML entered is not tested for validity, so be sure to test it prior to entering it into the DocuPro footer.

Each time DocuPro is run the last footer that was entered will be displayed. This allows the user to enter information only once instead of each time DocuPro is run.

Generating the Documentation

To generate the documentation press the Finish button.

Figure 3: Waiting to Generate the Documentation

The Results

Once the Finish button is pressed DocuPro examines all the components of the Visual Basic project and documents it based upon the documentation level requested. The HTML documents generated by DocuPro are created in the specified folder. Any previous versions are overwritten without confirmation.

The parent HTML document will be created in the target folder along with and one additional HTML document for each class, module, form and document contained in the project based on the level of documentation chosen.

Figure 4: Resulting Parent HTML Document

In order to avoid overwriting any typical HTML documents (such as Default.htm) a standardized naming methodology has been employed. The name that each HTML document is assigned is based on the name of the component and the type of component. The HTML document name has the general form of:

<ComponentName>_<ComponentType>_doc.htm

For Example, the documentation for a class component (.CLS file) named MyClass is written to: MyClass_cls_doc.htm.

Note: The component name used by DocuPro is not the component’s file name. Rather it is the name assigned to the file within the properties window when the component is selected in the project browser.

All generated documentation is available through hyperlinks contained in the parent document. This document will have a name of the form <projectName>_prj_doc.htm.

DocuPro Formatting

The information contained in the documentation generated by DocuPro comes from only two sources: the actual source code of the Visual Basic project and DocuPro comment blocks within that source code.

Source Code Information

When generating documentation DocuPro examines every class, form, control and property page contained in a Visual Basic project. If the level of documentation indicates that a component should be included in the documentation then it is processed by DocuPro. When DocuPro processes a Visual Basic project component each method and property is examined to determine whether or not it should be included in the documentation. Non-public properties and methods will only be included in the developer level documentation.

The name and type of each property are placed in the documentation. For functions and subroutines the name, return type, and the name and type of all arguments are included in the documentation.

DocuPro Comment Blocks

In addition to base level information extracted from the source code DocuPro examines specially formatted comment blocks (DocuPro comment Blocks) placed within the code and includes information in the generated HTML documentation. DocuPro comment blocks are only recognized if when they appear in the source code at two locations.

· Component Declaration Section: The declaration section of a Visual Basic from, class, module, property page, control or document can contain a DocuPro comment block. This comment block is used as the lead information on the component’s HTML documentation.

· Before a function, subroutine or property: Any information in a DocuPro comment block in the lines of source code directly before a function, subroutine or property will be placed in the documentation for that particular function, subroutine or property.

DocuPro comment blocks start with a comment line containing a single quote mark (the standard comment character) followed by two asterisks (‘**). The DocuPro comment block continues until a comment line that contains only a single quote followed by an asterisk (‘*). Only comment lines can exist between the DocuPro comment block opening and closing lines.

'**

' Storage wrapper for variants that provides tracing and read only protection.

' @describe

' This class provides a useful wrapper around Visual Basic's Variant

' data type. Using this class, variables may be created with a Read Only

' property and provide for Read/Write/Destroy tracing capabilities.

' @author Andrew F. Friedl

There are two principle sections to the body of a DocuPro comment block. The short description and the tags section. The short description begins on the line after the DocuPro comment block opening line and extends up to the first line containing a valid DocuPro tag. All text placed in these lines is considered to be part of the short comment. New line and comment characters (the single quote mark at the beginning of the line) are removed. All white space (extra spaces and tabs) are compressed (as in HTML).

The tags section is made up of one or more special DocuPro tags. All DocuPro tags begin with the ‘at’ character, “@” followed by the name of the tag. DocuPro tags are case-insensitive. A list of the available DocuPro tags is given in the next section.

A DocuPro tag should be followed by a minimum of one white space character. This can be a space, tab or even a new line. All text after the white space (up to the next DocuPro tag) is considered to be the value for the DocuPro tag. This may be plain text or HTML. The tag value continues up to the beginning of the next valid DocuPro tag or the end of the DocuPro comment block.

General Usage Notes

The information placed in DocuPro tags should be short and but descriptive.

DocuPro generates documentation in HTML format. Any HTML included in the value of a DocuPro tag is passed directly to the final documentation. This allows additional formatting (including the use of graphics, ActiveX controls, etc…) within the final documentation. However using HTML can become burdensome to maintain and reduce the readability of the comments within the source code. HTML should be sparingly within DocuPro comment blocks.

Since the resulting documentation is in HTML format all contiguous white space (including tabs and new lines) contained in a DocuPro comment block is compressed into a single space in the resulting documentation. This allows comments to be formatted to be readable within the source code and still be presented in the documentation in a professional manner.

DocuPro allows HTML to be assigned to the value of a DocuPro tag. This will be passed along to the generated documentation. The HTML is not validated. In addition, the <PRE></PRE> tag is not supported and should not be used. If additional formatting is required in the generated documentation the <BR> tag can be used to some effect.

Not all DocuPro tags can be used in every DocuPro comment block. Some of the DocuPro tags are only valid in a DocuPro comment block that precedes a method or property.

DocuPro Tags are case insensitive. So, @describe will have the same effect as @DESCRIBE.

DocuPro Tags

@describe

This tag provides for a long description to be associated with the DocuPro comment block. Long descriptions can be included in both the declaration section of a Visual Basic project component and in any method or property comment block. When used in a method comment block, the long description will be placed in the method’s detail section of the resulting documentation.

@author

This tag allows one or more authors to be credited for a given component, such as a class, form or module. There can be multiple @author tags in a single DocuPro comment block. A separate tag should be used for each author to be credited.

@revised

The @revised tag provides a mechanism to include source code revision history in the documentation. There can be multiple @revised tags in a single DocuPro comment block. Each revision to be documented should use a separate @revised tag.

@copyright

The @copyright tag is used to include a copyright notice in the component’s HTML documentation page. This not the same copyright field from the projects properties dialog box within the Visual Basic environment. The use of the @copyright tag is intended for copyrighting the HTML documentation.

@param

This tag is used to include information about parameters that are passed into functions, methods, and subroutines. One @param tag should be used for each parameter to be documented. This DocuPro tag cannot be used in the DocuPro comment block in a component’s declaration section.

@returns

This tag is used to document the return value of a property or function. There should be only one @returns tag for a given DocuPro comment block. This DocuPro tag cannot be used in the DocuPro comment block in a component’s declaration section.

Contacting BlackBox

If you should have any questions or comments regarding DocuPro please direct these to: affriedl@ozarkisp.net, or friedls@alltel.net.