如何让Doxygen识别显示Fortran主程序内局部代码块的注释

问题原因 #

Doxygen默认仅会提取顶层可识别实体的注释，包括program、子程序、模块、全局变量、子程序形参等，你写在循环、条件分支这类内部执行逻辑块前的!>注释，默认不属于提取范围，所以不会被展示。
你之前的注释写法对子程序、模块生效，是因为这两类都属于Doxygen默认识别的顶层实体，不需要额外开启提取权限。

解决方法 #

你可以按照以下两种方案调整，按需选择即可：

方案1：修改Doxygen配置文件（通用） #

打开你项目对应的Doxyfile配置文件，修改以下三个参数：

• 将EXTRACT_ALL设置为YES：强制Doxygen提取所有层级实体的注释，包括程序内部的代码块注释
• 确保OPTIMIZE_FOR_FORTRAN设置为YES：开启Fortran语法专属优化，大幅提升Fortran语法、注释的识别准确率
• 将INTERNAL_DOCS设置为YES：允许提取标记为内部属性的内容，程序内部逻辑块的注释默认归为这类

修改完成后重新执行doxygen Doxyfile生成文档即可。

方案2：注释显式标记（无需全开提取权限） #

如果不想开启EXTRACT_ALL导致提取太多无关内容，可以给需要展示的内部注释显式加Doxygen标记，明确告知需要提取，示例修改如下：

!> This is a test.
program main

    implicit none

    integer :: i
    real :: a

    !> @brief THIS IS A LOOP!
    !> 这里可补充循环的功能、边界条件等额外说明
    do i = 1,10
        a = 2.0*i
        write(*,*) a
    end do

end program main

之后再重新生成文档即可识别该注释。

内容的提问来源于stack exchange，提问作者Yinjian Zhao