vba 如何使用 Doxygen 记录 Visual Basic

How to document Visual Basic with Doxygen

提问by antonio

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

我正在尝试在 Windows 中为 Visual Basic 使用一些 Doxygen 过滤器。

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.basand, by means of his vbfilter.awk, I issued:

我从基于 gawk 的 Vsevolod Kukol 过滤器开始。没有那么多方向。所以我开始使用他自己的注释 VB 代码VB6Module.bas ，并通过他的vbfilter.awk，我发出：

gawk -f vbfilter.awk VB6Module.bas  

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

这会在 stdin 上输出类似 C 的代码。因此我将它重定向到一个文件：

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

I created this Doxygen test.cfgfile:

我创建了这个 Doxygentest.cfg文件：

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.basfrom awkout.txt. The warning stopped, but in both cases the documentation produced was just a single page with the project name.

Doxygen 抱怨说“在 \file 语句中作为第二个参数提供的名称 'VB6Module.bas' 不是输入文件。” 我@file VB6Module.bas从 中删除了评论awkout.txt。警告停止了，但在这两种情况下，生成的文档都只是一个包含项目名称的页面。

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

我还在 Python vbfilter.py 中尝试了 Basti Grembowietz 的替代过滤器。再次没有文档，再次产生错误并且没有任何有用的输出。

采纳答案by antonio

After trials and errors I solved the problem.

经过反复试验，我解决了这个问题。

I was unable to convert a .basfile 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 .basfile comments properly.

我无法将.bas文件转换为可以将其作为输入传递给 Doxygen 的格式。无论如何，按照@doxygen 用户的建议，我能够创建一个 Doxygen 配置文件，以便它可以.bas正确解释文件注释。

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:

给定文件VB6Module.bas（由 Doxygen-VB-Filter 作者，Vsevolod Kukol 编写），注释为适用于 Visual Basic 的 Doxygen 样式，我编写了 Doxygen 配置文件，test.cfg如下：

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.mdis any Markdown file that can used as the main documentation page.

• vbfilter.batcontains:

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

• vbfilter.awkby the filter author is assumed to be in the same folder as the input files to be documented and obviously gawkshould be in the path.

• readme.md是任何可以用作主文档页面的 Markdown 文件。

• vbfilter.bat包含：

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

• 假设过滤器作者的vbfilter.awk与要记录的输入文件位于同一文件夹中，显然 gawk应该在路径中。

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.htmlcontains the proper documentation as extracted by the ".bas" and the Markdown files.

现在test\html\index.html包含由“.bas”和 Markdown 文件提取的正确文档。

回答by displayname

Alright I did some work:

好吧，我做了一些工作：

You can download this .zip file. It contains:

您可以下载此 .zip 文件。它包含了：

• MakeDoxy.basThe macro that makes it all happen
• makedoxy.cmdA shell script that will be executed by MakeDoxy
• configurationFolder 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.
• sourceFolder that contains example source code for doxygen

• MakeDoxy.bas实现这一切的宏
• makedoxy.cmd将由 MakeDoxy 执行的 shell 脚本
• 配置文件夹，其中包含创建 doxygen 文档所需的 doxygen 和 gawk 二进制文件以及一些已被 OP 使用的其他过滤文件。
• source包含 doxygen 示例源代码的文件夹

---

---

How To Use:

如何使用：

Note:I tested it with Excel 2010

注意：我用 Excel 2010 测试过

1. Extract VBADoxy.zipsomehwere (referenced as <root>from now on)
   
   
2. Import MakeDoxy.basinto your VBA project.
   You can also import the files from sourceor 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

1. 提取VBADoxy.zipsomehwere（<root>从现在开始引用）
   
   
2. 将MakeDoxy.bas导入您的 VBA 项目。
   您也可以从源文件导入文件或使用您自己的 doxygen 记录的 VBA 代码文件，但在同一个 VBA 项目中至少需要一个记录文件。
   
   
3. 将“Microsoft Visual Basic for Applications Extensibility 5.3”或更高版本添加到您的 VBA 项目参考（未使用较低版本对其进行测试）。导出部分（VBProject、VBComponent）需要它。
   
   
   
   
4. 运行宏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>\sourceafterwards
   It is okay to delete those files. They will notbe removed from your VBA Project.
3. MakeDoxywill export all .bas, clsand .frmfiles to location:
   <root>\source\<modulename>\<modulename>(.bas|.cls|.frm)
4. cmd.exewill be commanded to run makedoxy.cmdand delete <root>\sourceif you've chosen that way which alltogether will result in your desired documentation.

1. 您将被要求提供<root>文件夹。
2. 如果你想删除你会被要求<root>\source以后
   这是正常删除这些文件。它们不会从您的 VBA 项目中删除。
3. MakeDoxy会将所有.bas,cls和.frm文件导出到以下位置：
   <root>\source\<modulename>\<modulename>(.bas|.cls|.frm)
4. cmd.exe如果您选择了这样的方式，将被命令运行makedoxy.cmd和删除<root>\source，这将导致您想要的文档。

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

MakeDoxy.bas.log每次执行MakeDoxy 时都会重新创建一个日志文件。

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

configuration\vbdoxy.cfg如果你想改变 doxygens 的行为，你可以玩一点。

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

还有一些改进的空间，但我想这是一个可以使用的东西。