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, or download the DocuPro
archive from the BlackBox Website or your email program.

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
' @copyright    1997.04.10, BlackBox Software & Consulting
'*

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: friedls@alltel.net.


Upgrading to the Commercial Version:

If you are pleased with the functionality and performance of the DocuPro Add-In,
you may wish to upgrade to the commercial version.  You can do this by contacting
BlackBox at friedls@alltel.net or by sending check or money order for $99.95 to

Andrew Friedl
BlackBox Software & Consulting
HC 79 Box 164
Marshall, AR 72650

To insure correct processing of your order be sure to send your
email address and a phone number where you may be contacted.  Also
indicate wether you would like the software to be emailed direct or
via diskette through standard postal carrier.