如何在Doxygen中内联源代码

Question

我想要使用doxygen记录包含函数的Fortran模块。

我的问题是，我找不到一种方法将函数体包含在函数文档中。只有一个到位置的链接，而不是实际的源代码。

目前，我的源代码看起来像这样：

!> @brief      Get a starting time.
!> @details    Get an object with time information.
!> @return     returns the time with high precision
FUNCTION get_start_time() RESULT(stime)
  TYPE (time) :: stime

  CALL SYSTEM_CLOCK(stime%count, stime%rate, stime%max)
END FUNCTION

我的doxygen配置（SOURCES部分）如下：

SOURCE_BROWSER         = YES
INLINE_SOURCES         = YES
STRIP_CODE_COMMENTS    = YES
REFERENCED_BY_RELATION = YES
REFERENCES_RELATION    = YES
REFERENCES_LINK_SOURCE = YES
SOURCE_TOOLTIPS        = YES
USE_HTAGS              = NO
VERBATIM_HEADERS       = YES

我也尝试使用@code和@endcode标记源代码，但这也不起作用。

我该怎么做才能直接将源代码放到文档中呢？

---

第一次编辑：我尝试了@cheeseminer的解决方案。所以上面的代码现在看起来像：

!> @brief      Get a starting time.
!> @details    Get an object with time information.
!> @return     returns the time with high precision
!> @par        Code
!> @snippet    folder/file.F90 get_start_time
!! [get_start_time]
FUNCTION get_start_time() RESULT(stime)
  TYPE (time) :: stime

  CALL SYSTEM_CLOCK(stime%count, stime%rate, stime%max)
END FUNCTION
!! [get_start_time]

不幸的是，块标识命令（前面带有!!）出现在文档和/或完整源代码中。 在Fortran中正确的方法是什么？

或者是否有更好的方法来解决我的初始问题？

---

第二次编辑：我找到了一个隐藏块标识的解决方法。 我将它们包裹在@internal命令中。

!> @internal [get_start_time]

---

第三次编辑：我现在正在使用@Michael的建议，将块ID作为HTML注释包含在内。

!> <!-- [get_start_time] -->

---

第四次编辑：我发布了一个关于别名的后续问题。

- Stefan

---

我自己没有使用过Doxygen来处理Fortran，但是看了一下手册，似乎你需要在片段标记行中使用“!>”——至少对于第二个标记行是这样的。需要使用“@internal”似乎并不合理。 - Cheeseminer

通过移除 @internal 并使用 !> 来获取 !> [get_start_time]，我在文档中得到了文本 "[get_start_time]"（两次），这并不理想。@internal 隐藏了这些出现。 - Stefan

嗯，不太好，我同意。恐怕我现在没有更多的建议了。 - Cheeseminer

只需使用普通注释，doxygen 仍然可以找到它。 - Michael

@Michael 你是对的，Doxygen可以找到它。但是这种方式，注释将出现在完整的源代码列表中，因为它们未被选项 STRIP_CODE_COMMENTS 剥离。 - Stefan

啊，我明白了。那使用HTML注释怎么样？!> <!-- [get_start_time] !> - Michael

Answer 1

我认为你需要的是@snippet。相关的手册页面在这里。你还需要在doxyfile中提供到“example”代码的路径。 @code更多地是一个格式化命令。如果你只有一些短的这样的部分，最好将代码复制到注释中，并使用@code进行格式化，但如果代码示例可能会更改，则应该使用snippet，尽管它会引入源代码的混乱。

- Cheeseminer

---

感谢您的第一次尝试。不幸的是，我在块标记方面遇到了一些问题，这些标记仍然出现在完整的源代码或文档部分中... - Stefan