How to document Visual Basic with Doxygen

问题:

I am trying to use some Doxygen filter for Visual Basic in Windows.

I started with Vsevolod Kukol filter, based on gawk. There are not so many directions. So I started using his own commented VB code VB6Module.bas and, by means of his vbfilter.awk, I issued:

gawk -f vbfilter.awk VB6Module.bas  

This outputs a C-like code on stdin. Therefore I redirected it to a file with:

gawk -f vbfilter.awk VB6Module.bas>awkout.txt

I created this Doxygen test.cfg file:

PROJECT_NAME      = "Test"
OUTPUT_DIRECTORY  = test
GENERATE_LATEX    = NO
GENERATE_MAN      = NO
GENERATE_RTF      = NO
CASE_SENSE_NAMES  = NO
INPUT             = awkout.txt
QUIET             = NO
JAVADOC_AUTOBRIEF = NO
SEARCHENGINE      = NO

To produce the documentation I issued:

doxygen test.cfg 

Doxygen complains as the "name 'VB6Module.bas' supplied as the second argument in the \file statement is not an input file." I removed the comment @file VB6Module.bas from awkout.txt. The warning stopped, but in both cases the documentation produced was just a single page with the project name.

I tried also the alternative filter by Basti Grembowietz in Python vbfilter.py. Again without documentation, again producing errors and without any useful output.

回答1:

After trials and errors I solved the problem.

I was unable to convert a .bas file in a format such that I can pass it to Doxygen as input. Anyway, following @doxygen user suggestions, I was able to create a Doxygen config file such that it can interpret the .bas file comments properly.

Given the file VB6Module.bas (by the Doxygen-VB-Filter author, Vsevolod Kukol), commented with Doxygen style adapted for Visual Basic, I wrote the Doxygen config file, test.cfg, as follows:

PROJECT_NAME      = "Test"
OUTPUT_DIRECTORY  = test
GENERATE_LATEX    = NO
GENERATE_MAN      = NO
GENERATE_RTF      = NO
CASE_SENSE_NAMES  = NO
INPUT             = readme.md VB6Module.bas
QUIET             = YES
JAVADOC_AUTOBRIEF = NO
SEARCHENGINE      = NO
FILTER_PATTERNS   = "*.bas=vbfilter.bat"

where:

• readme.md is any Markdown file that can used as the main documentation page.

• vbfilter.bat contains:

  @echo off gawk.exe -f vbfilter.awk "%1%"

• vbfilter.awk by the filter author is assumed to be in the same folder as the input files to be documented and obviously gawk should be in the path.

Running:

doxygen test.cfg 

everything is smooth, apart two apparently innocuous warnings:

gawk: vbfilter.awk:528: warning: escape sequence `\[' treated as plain `[' 
gawk: vbfilter.awk:528: warning: escape sequence `\]' treated as plain `]' 

Now test\html\index.html contains the proper documentation as extracted by the ".bas" and the Markdown files.

回答2:

Alright I did some work:

You can download this .zip file. It contains:

• MakeDoxy.bas The macro that makes it all happen
• makedoxy.cmd A shell script that will be executed by MakeDoxy
• configuration Folder that contains doxygen and gawk binaries which are needed to create the doxygen documentation as well as some additional filtering files which were already used by the OP.
• source Folder that contains example source code for doxygen

---

How To Use:

Note: I tested it with Excel 2010

1. Extract VBADoxy.zip somehwere (referenced as <root> from now on)
   
   
2. Import MakeDoxy.bas into your VBA project.
   You can also import the files from source or use your own doxygen-documented VBA code files but you'll need at least one documented file in the same VBA project.
   
   
3. Add "Microsoft Visual Basic for Applications Extensibility 5.3" or higher to your VBA Project References (did not test it with lower versions). It's needed for the export-part (VBProject, VBComponent).
   
   
   
   
4. Run macro MakeDoxy

---

What is going to happen:

1. You will be asked for the <root> folder.
2. You will be asked if you want to delete <root>\source afterwards
   It is okay to delete those files. They will not be removed from your VBA Project.
3. MakeDoxy will export all .bas, cls and .frm files to location:
   <root>\source\<modulename>\<modulename>(.bas|.cls|.frm)
4. cmd.exewill be commanded to run makedoxy.cmd and delete <root>\source if you've chosen that way which alltogether will result in your desired documentation.

A logfile MakeDoxy.bas.logwill be re-created each time MakeDoxy is executed.

You can play with configuration\vbdoxy.cfg a little if you want to change doxygens behavior.

There is still some room for improvements but I guess this is something one can work with.