如何使用Doxygen记录Visual Basic代码

Question

我正在尝试在Windows中使用一些Doxygen筛选器来处理Visual Basic。

我开始使用基于gawk的Vsevolod Kukol过滤器。 方向并不是很多。 因此，我开始使用他自己注释的VB代码VB6Module.bas，并通过他的vbfilter.awk进行操作：

gawk -f vbfilter.awk VB6Module.bas  

这会在标准输入上输出类似C语言的代码。因此我用以下命令将其重定向到文件中：

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

我创建了这个Doxygen test.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

为了制作文档，我发布了以下内容：

doxygen test.cfg 

当我在 \file 语句中提供 "name 'VB6Module.bas' "作为第二个参数时，Doxygen会抱怨它不是一个输入文件。因此我从 awkout.txt 文件中移除了注释 @file VB6Module.bas，警告消失了，但是生成的文档都只有一个项目名称的单页。

我还尝试了 Basti Grembowietz 在 Python 中提供的另一种过滤方式 vbfilter.py，但仍然没有文档输出，同时产生错误且无任何有用的输出。

- antonio

---

我认为你应该看看INPUT_FILTER选项，并让Doxygen为你运行脚本。 - doxygen

我作为答案发布了一条相当长的评论。 - antonio

Answer 1

经过多次尝试，我解决了这个问题。

我无法将 .bas 文件转换为可用作Doxygen输入的格式。但是，根据 @doxygen 用户的建议，我成功创建了一个Doxygen配置文件，使其可以正确地解释 .bas 文件中的注释。

假设有文件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"

其中:

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

• vbfilter.bat 包含：

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

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

运行:

doxygen test.cfg 

一切都很顺利，除了两个看似无害的警告：

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

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

- antonio

---

这对 .cls 文件也适用吗？还是只适用于过程式代码？ - Stefan Falk

@StefanFalk：我没有尝试过（或者我尝试过但忘记了）。无论如何，vbfilter.awk 肯定可以接受和解析 .cls 文件，并通过更新配置文件来传递过滤后的输入到 doxygen。然后我不知道是否会出现任何特定的问题。 - antonio

好的，谢谢。我已经尝试过了，它当然可以解析，但问题是在运行doxygen后，单个文件夹被视为包含所有函数的“包”。这意味着ModuleName.bas和ClassName.cls中的函数将被混合在一起。一个简单的解决方案可能是将所有文件移动到单独的文件夹中，并使用相同的名称。这将为每个文件创建单独的文档，并且函数条目例如看起来像Public ClassName.FunctionName() As Integer。 - Stefan Falk

如果您找到解决方案，请将其作为答案分享。 - antonio

Answer 2

好的，我做了一些工作：

你可以下载this .zip文件。它包括：

• MakeDoxy.bas 这个宏使所有操作都能实现
• makedoxy.cmd 一个将被MakeDoxy执行的shell脚本
• configuration 文件夹，其中包含创建doxygen文档所需的doxygen和gawk二进制文件以及一些附加过滤文件，这些文件已经被OP使用过。
• source 文件夹，其中包含用于doxygen的示例源代码

---

如何使用：

注意：我在Excel 2010上进行了测试。

1. 将VBADoxy.zip解压到某个地方（从现在开始称为<root>）
   
   
2. 将MakeDoxy.bas导入到您的VBA项目中。
   您也可以导入来自source的文件或使用您自己的已用doxygen文档记录的VBA代码文件，但您至少需要在同一VBA项目中有一个记录文件。
   
   
3. 将“Microsoft Visual Basic for Applications Extensibility 5.3”或更高版本添加到您的VBA项目引用中（未测试较低版本）。这是导出部分所需的（VBProject，VBComponent）。
   
   
   
   
4. 运行宏MakeDoxy

---

即将发生的事情：

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 ，所有这些将会实现您所需的文档。

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

如果您想更改 Doxygen 的行为，则可以稍微玩一下 configuration\vbdoxy.cfg。

还有一些改进的空间，但我想这是可以解决的问题。

- Stefan Falk

---

+1，干得好，我现在手头没有VB，但我会尽快测试它。 - antonio

好的 :) 我认为它还不完美，但现在它不会再将模块混合在一起了。也许通过更改doxy .cfg文件也可以防止这种情况，但我还没有找到任何东西。但是这样一来，人们也可以将其用作“一次性导出所有模块文件”的工具 :D - Stefan Falk

压缩文件的链接已经失效。[此 .zip 文件][1] [1]: https://dl.dropboxusercontent.com/u/30731675/VBADoxy.zip - Adolfo Correa

@displayname 您好，很抱歉打扰您，能否重新上传Zip文件或编辑答案，将其实际内容（至少是可行部分）复制到答案中？ - L8n

@L8n 抱歉，但我恐怕已经没有这个文件了。 - Stefan Falk