How to document Visual Basic with Doxygen

documentation, doxygen, vb.net, vb6, vba

Solution

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.

Problem

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.

Original source