针对 Verilog 的 Doxygen

最近学习了 Doxygen，它可以帮助我们生成美观的文档。Doxygen 支持的程序语言中包含 VHDL，但是不包含 Verilog。

那么问题就又来了：有没有一个支持 Verilog 的类似 Doxygen 的程序？

答案当然是：有， Doxverilog

机智的网友早就遇到了和我一样的问题：

Documentation generator for Verilog

Documenting Verilog (AMS) using Doxygen/Doxverilog

Doxverilog has been updated

我搜到了两个工具：一个是 perl 脚本v2html，另一个就是 Doxverilog。前者生成的页面美观性实在不敢恭维，理想工具当然是 Doxverilog。

Doxverilog

Doxverilog is a nativ verilog parser (Verilog 2001) for Doxygen. After installing this patch you can documentate your verilog project similar to VHDL in Doxygen. Patch against the doxygen-1.7.0 version.

Doxverilog 基于 Doxygen ，只是额外添加了对 Verilog 语言的支持。它托管在 sourceforge 上的压缩包貌似是损坏的，不能正常解压，幸好在 Github 上的还是好的：

Doxverilog on Github

关于 Doxverilog 的安装使用方法，github 上已经说的很清楚了，下面只记录一下我遇到的问题。

Installation

安装步骤：

1. patch

   patch -F3 -p0  < linux.patch
   

2. compile

   ./configure
   make
   make install
   

3. 写本文时，Doxverilog 的版本号是 2.7，对应的 Doxygen 的版本号是 1.8.1，而 Doxygen 官网上的版本已经更新到了 1.8.9，如果最新版本可能在编译的时候报错。

4. 在 patch 时，可能会遇到询问，一路 y 下去即可。

5. 在 compile 时，可能会报错，我遇到的报错是 vhdlparse.cpp 缺少行末分号的小问题，自己添加就行。

6. 编译安装完成之后，我们应该可以使用一个文档来测试一下，如果生成的配置文件中包含 OPTIMIZE-OUTPUT-VERILOG 这个选项，那么就说明破解安装成功了。

Configuration

在修改配置文档时，除了常规的配置选项之外，对于 Verilog 我们还需要额外注意一下几个选项：

• OPTIMIZE-OUTPUT-VERILOG = YES 针对 Verilog 进行输出优化

• FILE-PATTERNS = *.v 标明选择 verilog 源文件

Documenting Verilog/VHDL

注释规则：

• 对于 Verilog 的注释规则，和 VHDL 类似，唯一的不同之处在于 VHDL 使用 --! 来开始注释，Verilog 使用 //% 作为注释的开头。

• VHDL 中使用单行的 --! 来开始 brief description，使用多行的 --! 开始 detailed description。

• Verilog 使用单行的 //% 开始 brief description，使用多行的 //% 开始 detailed description。

• 所有的注释都在对应代码的前面，只有一个例外：端口的 brie description 可以写在代码后，而且不用像 C++ 中一样修改注释的头部

example:

下面是 Doxygen 官网是 VHDL 注释的例子：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

-------------------------------------------------------
--! @file
--! @brief 2:1 Mux using with-select
-------------------------------------------------------

--! Use standard library
library ieee;
--! Use logic elements
    use ieee.std-logic-1164.all;

--! Mux entity brief description

--! Detailed description of this 
--! mux design element.
entity mux-using-with is
    port (
        din-0   : in  std-logic; --! Mux first input
        din-1   : in  std-logic; --! Mux Second input
        sel     : in  std-logic; --! Select input
        mux-out : out std-logic  --! Mux output
    );
end entity;

--! @brief Architecture definition of the MUX
--! @details More details about this mux element.
architecture behavior of mux-using-with is
begin
    with (sel) select
    mux-out <= din-0 when '0',
               din-1 when others;
end architecture;

生成的 结果。

我写的 Verilog 的注释：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

//% @file mycounter.v
//% @brief Implementation file of module mycounter.
//% 
//% @author Qian Gu
//% @version 1.0
//% @date 2015-01-20

//% This is a test project,
//% it's a increase counter module 256.
//%
module mycounter(
    clk,rst,dout
 );

// Port Declaratiosn
    input clk; //% clock signal
    input rst; //% reset siganl, active high

    output reg [7:0] dout; //% count result

// Main Body of Code

always @ (posedge clk or negedge rst) begin
    if (!rst) begin
        dout <= 8'b0;
    end
    else begin
        dout <= dout + 1;
    end
end

endmodule

Ref

doxygen manual

doxverilog