Permalink
Switch branches/tags
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
166 lines (113 sloc) 5.72 KB
-----------------------------------------------------------------------------
README.txt - How to use Doxygen VB documentation filter by Vsevolod Kukol
-----------------------------------------------------------------------------
Creation: 21.06.2010 Vsevolod Kukol
Last Update: 09.10.2011 Vsevolod Kukol
Copyright (c) 2010-2011 Vsevolod Kukol, sevo(at)sevo(dot)org
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
Doxygen Visual Basic filter
===========================
The Doxygen Visual Basic filter is an awk script that converts
Classic VB (VB6) and VB.NET code syntax to a C#-like syntax, so it can be
read and understood by Doxygen.
It is inspired by the Visual Basic (classic) filter script written
by Mathias Henze. More information about his script can be found in
the Helper Tools section (http://www.stack.nl/~dimitri/doxygen/helpers.html)
on the Doxygen homepage.
How dows it work
----------------
Doxygen can preprocess all sources using a source filter. A source filter
must be executable, accept the name of the source path as last parameter
and print the resulting source to STDOUT. See the Doxygen manual for
more information.
The vbfilter.awk script is a AWK script, which can be executed using
gawk. Gawk reads the source files line by line, applys vbfilter.awk on
it and passes the output to doxygen.
Instructions
------------
1. copy the vbfilter sources to a Doc directory in your project folder.
This can be done by checking out from svn using TortoiseSVN on Windows,
or the svn command on Linux:
svn checkout http://trac.sevo.org/svn/doxyvb/trunk Doc
The Doc folder should be created in your Project folder to generate
documentation for a single project.
If you use .NET and have a solution folder you could create Doc in the
solution folder to generate one single documentation for all projects.
For VB6 the structure could look like:
MyProject\MyProject.vbp
MyProject\[...]
MyProject\Doc\vbfilter.[bat|sh]
MyProject\Doc\vbfilter.awk
MyProject\Doc\[...]
For .NET the structure could look like:
MySolution\MySolution.sln
MySolution\[...]
MySolution\Doc\vbfilter.[bat|sh]
MySolution\Doc\vbfilter.awk
MySolution\Doc\[...]
MySolution\MyProject
2. Download and install the Doxygen 1.7.0 (or newer) distribution package
from the Doxygen download page:
http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc
Many Linux distributions have ready to use doxygen packages.
On Ubuntu you can simply do a:
sudo apt-get install doxygen
3. Optional: Install GraphViz if you want nice graphs in your documentation
Link: http://www.graphviz.org/Download_windows.php
4. create the Doc\Doxyfile configuration file with Doxywizard or any
text editor (like Notepad++). You can use `samples\Doxyfile` as template.
If you use Doxywizard, switch to the "Expert" tab to see all options.
Important configuration options:
PROJECT_NAME: set the name of your project here
OUTPUT_DIRECTORY: full path of the Doc folder, or simply "Doc"
if you want to use the `make.[bat|sh]` scripts.
EXTENSION_MAPPING:
For VB-NET: "= .vb=csharp"
For VB6: "= .cls=csharp .frm=csharp .ctl=csharp .bas=csharp"
INPUT: full path to the sopurces (usually the folder containing `Doc`),
or simply `.` in order to use the `make.[bat|sh]` scripts.
FILE_PATTERNS:
For VB-NET: = *.vb
For VB6: = *.cls *.bas *.frm *.ctl
INPUT_FILTER:
Windows: "\path\to\vbfilter.bat"
Linux: "path/to/vbfilter.sh"
HAVE_DOT - Set to YES, to enable Graphs in the documentation.
GraphViz (Step 3) has to be installed for this feature.
Read the Doxygen manual for all other options under
http://www.stack.nl/~dimitri/doxygen/manual.html
NOTE: If you want to run Doxygen directly from inside Doxywizard,
set the working folder under:
"Step 1: Specify the working directory from which doxygen will run"
to the folder CONTAINING the Doc folder
(in most cases your Project or Solution folder!)
5. open vbfilter.awk in your favorite editor and edit the options in
the Configuration section as you like.
6. run Doc\make.bat or Doc/make.sh to generate the documentation.
Good to know
============
Integrating in Visual Studio or MonoDevelop
-------------------------------------------
You can configure Visual Studio and MonoDevelop to run make.bat each
time you build your project. This can be done in the project settings.
In VS you can create a custom shortcut icon to run make.bat manually.
Generating CHM (Windows Help)
-----------------------------
If you want Doxygen to generate CHM (Windows Help) files, install
the Microsoft HTML Help Workshop 1.3 (htmlhelp.exe) from
http://go.microsoft.com/fwlink/?LinkId=14188
Direct link: http://go.microsoft.com/fwlink/?LinkId=14188
set the path to hhc.exe using the HHC_LOCATION option
and enable the GENERATE_HTMLHELP option.
(Doxywizard: you'll find both in the HTML section)
GENERATE_HTMLHELP = YES
HHC_LOCATION = "C:/Program Files/HTML Help Workshop/hhc.exe"
Other formats
-------------
HTML output is enabled by default. You can additionally enable
RTF, LaTex and some other output formats. LaTex and PDF need
a complete LaText distribution to be installed. Read the
Doxygen manula for more information.