Question

是否可以在doxygen评论块中包含doxygen会忽略的内容？顺便说一句，我们可以在doxygen注释块中发表评论吗？

背景

我们正在将Fortran项目的代码内注释转换为doxygen-parseable格式，但该项目要求代码内注释中的内容由水平线描述。例如：

!> @brief Lorem ipsum dolor sit amet
!! ---------------------------------------------------------------------
!!
!! @param[in] p1  Description of p1
!! @param[in] p2  Description of p2
!! ---------------------------------------------------------------------
!!
!! More content here ....
!! ---------------------------------------------------------------------
!!
!! More content for another section
!! ---------------------------------------------------------------------
subroutine do_something(p1, p2)
  ! .... the code ...
end subroutine do_something

是否有命令/语法我可以为这些行添加前缀，以便doxygen会忽略它们？希望这一点不引人注目，不会影响评论的可读性。

我知道可以用来在预处理脚本中链接的INPUT_FILTER设置，但理想的解决方案是不依赖于其他脚本/工具的解决方案。

P.S。我很清楚，许多人会认为这些水平线不必要和/或分散注意力。但是，这是付款人规定的要求，并不是我可以自由改变的。

Answer 1

Doxygen支持一些HTML commands，包括HTML注释。该解决方案的好处是不需要对Doxyfile进行任何修改，并且比@I{ ---- }稍微分散注意力。

!> @brief Lorem ipsum dolor sit amet
!! <!----------------------------------------------------------------->
!!
!! @param[in] p1  Description of p1
!! @param[in] p2  Description of p2
!! <!----------------------------------------------------------------->
!!
!! More content here ....
!! <!----------------------------------------------------------------->
!!
!! More content for another section
!! <!----------------------------------------------------------------->
subroutine do_something(p1, p2)
  ! .... the code ...
end subroutine do_something

^{为了记录，这是我最终确定的解决方案。但是，我接受了DRH's answer，因为它为“在doxygen块中启用注释”提供了更通用的解决方案。}

Answer 2

如果您可以灵活地将字符用于水平线，则可以继续重复注释字符，doxygen将忽略它。类似的东西：

!> @brief Lorem ipsum dolor sit amet
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!!
!! @param[in] p1  Description of p1
!! @param[in] p2  Description of p2
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!!
!! More content here ....
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!!
!! More content for another section
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
subroutine do_something(p1, p2)
  ! .... the code ...
end subroutine do_something

Answer 3

您可以利用Doxygen的别名语法来忽略该行，但是它需要以前缀为前缀并以其他字符为后缀。例如，如果您定义了一个别名：

ALIASES                = I{1}=""

您可以使用注释中的别名来隐藏doxygen的水平中断：

!> @brief Lorem ipsum dolor sit amet
!! @I{-----------------------------------------------------------------}
!!
!! @param[in] p1  Description of p1
!! @param[in] p2  Description of p2
!! @I{-----------------------------------------------------------------}
!!
!! More content here ....
!! @I{-----------------------------------------------------------------}
!!
!! More content for another section
!! @I{-----------------------------------------------------------------}
subroutine do_something(p1, p2)
  ! .... the code ...
end subroutine do_something

Answer 4

您可以编写一个简单的过滤器来删除这些行。在perl中，它可能看起来像这样：

while (<>)
{
    if (m/^!! -{3,}/)
    {
        print "!!\n";
    }
    else
    {
        print;
    }
}

然后在INPUT_FILTER中配置Doxyfile以引用此脚本：

INPUT_FILTER = path/to/my/perl/script

忽略doxygen注释块中的行

4 个答案: